datagrid 2.0.0.pre.alpha → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37409811e25a50a023aa095fb8854424fea3867e137b8d212d619ba191307abe
-  data.tar.gz: 2485f8f3a8cf9d196011a584e680c345d147430ef3d263b151569ae10fc3ef69
+  metadata.gz: d4f9903c41d2efb4c914ddf949db685228644e1ba071e8e2337491e0b91e0bbd
+  data.tar.gz: 937aea06689389c091b3be16aabaa36d8c828b8a8e97f220eaad403975371c6e
 SHA512:
-  metadata.gz: 2974b76d03c7a3c014a3b853570ae0a11e2c137f0e4faea6be0dfcff45b49e4c64037298337e0f9e3028ecd64d938747770903469888339e6a43bbcc03330a59
-  data.tar.gz: 52d188d5c0e6a41a3f44061274695b5eee22f7c669c1814f26ae38cfeee364b66c8437ca85c55fa3a73d8fe3333e6c9820fda9b1e2ccee770d48bcba7d72bfe3
+  metadata.gz: b3a5ef4923f03bd41bc54c2cc8ad6261f4a1e3302c4aad83a58868d539d69527a6cf838ee6efdf621fa0a47dabd023fa041773dde723f35f0feaf59e0b5effe6
+  data.tar.gz: 0a4c6aca85619ab3a71c125717d6f6f5209eafcb7a509df76afaac91e70790f199fea2ac796ebb9c05d088c8f4d40b42c16d6a49a28661ae1da7703c86c1ff92

data/.yardopts

@@ -0,0 +1,2 @@
+--markup=markdown
+--readme=README.md

data/README.md

@@ -23,8 +23,6 @@ including admin panels, analytics and data browsers:
 * Sequel
 * Array (in-memory data of smaller scale)
 
-[Create an issue](https://github.com/bogdan/datagrid/issues/new) if you want more.
-
 ## Datagrid Philosophy
 
 1. Expressive DSL complements OOD instead of replacing it.
@@ -164,7 +162,7 @@ end
 Some formatting options are also available.
 Each column is sortable.
 
-[More about columns](https://github.com/bogdan/datagrid/wiki/Columns)
+[More about columns](https://rubydoc.info/gems/datagrid/Datagrid/Columns)
 
 ### Front end
 

data/datagrid.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
     "CHANGELOG.md",
     "README.md",
     "datagrid.gemspec",
+    ".yardopts",
   ]
   s.files += `git ls-files | grep -E '^(app|lib|templates)'`.split("\n")
   s.homepage = "https://github.com/bogdan/datagrid"
@@ -27,7 +28,7 @@ Gem::Specification.new do |s|
   s.metadata = {
     "homepage_uri" => s.homepage,
     "bug_tracker_uri" => "#{s.homepage}/issues",
-    "documentation_uri" => "#{s.homepage}/wiki",
+    "documentation_uri" => "https://rubydoc.info/gems/datagrid",
     "changelog_uri" => "#{s.homepage}/blob/main/CHANGELOG.md",
     "source_code_uri" => s.homepage,
     "rubygems_mfa_required" => "true",

data/lib/datagrid/columns.rb

@@ -2,6 +2,7 @@
 
 require "datagrid/utils"
 require "active_support/core_ext/class/attribute"
+require "datagrid/columns/column"
 
 module Datagrid
   # Defines a column to be used for displaying data in a Datagrid.
@@ -199,33 +200,30 @@ module Datagrid
   #       presenter.user.created_at
   #     end
   module Columns
-    require "datagrid/columns/column"
-
     # @!method default_column_options=(value)
-    # @param [Hash] value default options passed to #column method call
-    # @return [Hash] default options passed to #column method call
-    # @example
-    #   # Disable default order
-    #   self.default_column_options = { order: false }
-    #   # Makes entire report HTML
-    #   self.default_column_options = { html: true }
+    #   @param [Hash] value default options passed to {#column} method call
+    #   @return [Hash] default options passed to {#column} method call
+    #   @example Disable default order
+    #     self.default_column_options = { order: false }
+    #   @example Makes entire report HTML
+    #     self.default_column_options = { html: true }
 
     # @!method default_column_options
-    # @return [Hash]
-    # @see #default_column_options=
+    #   @return [Hash] default options passed to {#column} method call
+    #   @see #default_column_options=
 
     # @!method batch_size=(value)
-    # @param [Integer] value Specify a default batch size when generating CSV or just data. Default: 1000
-    # @return [Integer] Specify a default batch size when generating CSV or just data.
-    # @example
-    #   self.batch_size = 500
-    #   # Disable batches
-    #   self.batch_size = nil
-    #
+    #   Specify a default batch size when generating CSV or just data.
+    #   @param [Integer] value a batch size when generating CSV or just data. Default: 1000
+    #   @return [void]
+    #   @example Set batch size to 500
+    #     self.batch_size = 500
+    #   @example Disable batches
+    #     self.batch_size = nil
 
     # @!method batch_size
-    # @return [Integer]
-    # @see #batch_size=
+    #   @return [Integer]
+    #   @see #batch_size=
 
     # @visibility private
     # @param [Object] base
@@ -253,37 +251,31 @@ module Datagrid
         filter_columns(columns_array, *column_names, data: data, html: html)
       end
 
-      # Defines new datagrid column
-      #
+      # Defines a new datagrid column
       # @param name [Symbol] column name
       # @param query [String, nil] a string representing the query to select this column (supports only ActiveRecord)
-      # @param options [Hash{Symbol => Object}] hash of options
       # @param block [Block] proc to calculate a column value
+      # @option options [Boolean, String] html Determines if the column should be present
+      #   in the HTML table and how it is formatted.
+      # @option options [String, Array<Symbol>] order Determines if the column can be sortable and
+      #   specifies the ORM ordering method.
+      #   Example: `"created_at, id"` for ActiveRecord, `[:created_at, :id]` for Mongoid.
+      # @option options [String] order_desc Specifies a descending order for the column
+      #   (used when `:order` cannot be easily reversed by the ORM).
+      # @option options [Boolean, Proc] order_by_value Enables Ruby-level ordering for the column.
+      #   Warning: Sorting large datasets in Ruby is not recommended.
+      #   If `true`, Datagrid orders by the column value.
+      #   If a block is provided, Datagrid orders by the block's return value.
+      # @option options [Boolean] mandatory If `true`, the column will never be hidden by the `#column_names` selection.
+      # @option options [Symbol] before Places the column before the specified column when determining order.
+      # @option options [Symbol] after Places the column after the specified column when determining order.
+      # @option options [Boolean, Proc] if conditions when a column is available.
+      # @option options [Boolean, Proc] unless conditions when a column is not available.
+      # @option options [Symbol, Array<Symbol>] preload Specifies associations
+      #   to preload for the column within the scope.
+      # @option options [Hash] tag_options Specifies HTML attributes for the `<td>` or `<th>` of the column.
+      #   Example: `{ class: "content-align-right", "data-group": "statistics" }`.
       # @return [Datagrid::Columns::Column]
-      #
-      # Available options:
-      #
-      # * <tt>html</tt> - determines if current column should be present in html table and how is it formatted
-      # * <tt>order</tt> - determines if this column could be sortable and how.
-      #   The value of order is explicitly passed to ORM ordering method.
-      #   Example: <tt>"created_at, id"</tt> for ActiveRecord, <tt>[:created_at, :id]</tt> for Mongoid
-      # * <tt>order_desc</tt> - determines a descending order for given column
-      #   (only in case when <tt>:order</tt> can not be easily reversed by ORM)
-      # * <tt>order_by_value</tt> - used in case it is easier to perform ordering at ruby level not on database level.
-      #   Warning: using ruby to order large datasets is very unrecommended.
-      #   If set to true - datagrid will use column value to order by this column
-      #   If block is given - datagrid will use value returned from block
-      # * <tt>mandatory</tt> - if true, column will never be hidden with #column_names selection
-      # * <tt>url</tt> - a proc with one argument, pass this option to easily convert the value into an URL
-      # * <tt>before</tt> - determines the position of this column, by adding it before the column passed here
-      # * <tt>after</tt> - determines the position of this column, by adding it after the column passed here
-      # * <tt>if</tt> - the column is shown if the reult of calling this argument is true
-      # * <tt>unless</tt> - the column is shown unless the reult of calling this argument is true
-      # * <tt>preload</tt> - spefies which associations of the scope should be preloaded for this column
-      # * `tag_options` - specify HTML attributes to be set for `<td>` or `<th>` of a column
-      #   Example: `{ class: "content-align-right", "data-group": "statistics" }`
-      #
-      # @see https://github.com/bogdan/datagrid/wiki/Columns
       def column(name, query = nil, **options, &block)
         define_column(columns_array, name, query, **options, &block)
       end
@@ -333,10 +325,10 @@ module Datagrid
       # Defines a model decorator that will be used to define a column value.
       # All column blocks will be given a decorated version of the model.
       # @return [void]
-      # @example
+      # @example Wrapping a model with presenter
       #   decorate { |user| UserPresenter.new(user) }
-      #
-      #   decorate { UserPresenter } # a shortcut
+      # @example A shortcut for doing the same
+      #   decorate { UserPresenter }
       def decorate(model = nil, &block)
         if !model && !block
           raise ArgumentError, "decorate needs either a block to define decoration or a model to decorate"
@@ -403,14 +395,16 @@ module Datagrid
       )
     end
 
-    # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns
     # @return [Array<String>] human readable column names. See also "Localization" section
     def header(*column_names)
       data_columns(*column_names).map(&:header)
     end
 
     # @param asset [Object] asset from datagrid scope
-    # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns
     # @return [Array<Object>] column values for given asset
     def row_for(asset, *column_names)
       data_columns(*column_names).map do |column|
@@ -419,7 +413,8 @@ module Datagrid
     end
 
     # @param asset [Object] asset from datagrid scope
-    # @return [Hash] A mapping where keys are column names and values are column values for the given asset
+    # @return [Hash] A mapping where keys are column names and
+    #   values are column values for the given asset
     def hash_for(asset)
       result = {}
       data_columns.each do |column|
@@ -428,7 +423,8 @@ module Datagrid
       result
     end
 
-    # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String,Symbol>] list of column names
+    #   if you want to limit data only to specified columns
     # @return [Array<Array<Object>>] with data for each row in datagrid assets without header
     def rows(*column_names)
       map_with_batches do |asset|
@@ -436,7 +432,8 @@ module Datagrid
       end
     end
 
-    # @param column_names [Array<String>] list of column names if you want to limit data only to specified columns
+    # @param column_names [Array<String, Symbol>] list of column names
+    #   if you want to limit data only to specified columns.
     # @return [Array<Array<Object>>] data for each row in datagrid assets with header.
     def data(*column_names)
       rows(*column_names).unshift(header(*column_names))
@@ -461,7 +458,7 @@ module Datagrid
       end
     end
 
-    # @param column_names [Array<String>]
+    # @param column_names [Array<String,Symbol>]
     # @param options [Hash] CSV generation options
     # @return [String] a CSV representation of the data in the grid
     #
@@ -514,7 +511,7 @@ module Datagrid
       columns(*column_names, data: data, html: true)
     end
 
-    # Finds a column definition by name
+    # Finds a column by name
     # @param name [String, Symbol] column name to be found
     # @return [Datagrid::Columns::Column, nil]
     def column_by_name(name)
@@ -522,22 +519,21 @@ module Datagrid
     end
 
     # Gives ability to have a different formatting for CSV and HTML column value.
-    #
-    # @example
+    # @example Formating using Rails view helpers
     #   column(:name) do |model|
     #     format(model.name) do |value|
     #       tag.strong(value)
     #     end
     #   end
-    #
+    # @example Formatting using a separated view template
     #   column(:company) do |model|
     #     format(model.company.name) do
-    #       render partial: "company_with_logo", locals: {company: model.company }
+    #       render partial: "companies/company_with_logo", locals: {company: model.company }
     #     end
     #   end
     # @return [Datagrid::Columns::Column::ResponseFormat] Format object
     def format(value, &block)
-      if block_given?
+      if block
         self.class.format(value, &block)
       else
         # don't override Object#format method
@@ -545,26 +541,26 @@ module Datagrid
       end
     end
 
+    # @param [Object] asset one of the assets from grid scope
     # @return [Datagrid::Columns::DataRow] an object representing a grid row.
     # @example
-    #  class MyGrid
-    #    scope { User }
-    #    column(:id)
-    #    column(:name)
-    #    column(:number_of_purchases) do |user|
-    #      user.purchases.count
-    #    end
-    #  end
+    #   class MyGrid
+    #     scope { User }
+    #     column(:id)
+    #     column(:name)
+    #     column(:number_of_purchases) do |user|
+    #       user.purchases.count
+    #     end
+    #   end
     #
-    #  row = MyGrid.new.data_row(User.last)
-    #  row.id # => user.id
-    #  row.number_of_purchases # => user.purchases.count
+    #   row = MyGrid.new.data_row(User.last)
+    #   row.id # => user.id
+    #   row.number_of_purchases # => user.purchases.count
     def data_row(asset)
       ::Datagrid::Columns::DataRow.new(self, asset)
     end
 
     # Defines a column at instance level
-    #
     # @see Datagrid::Columns::ClassMethods#column
     def column(name, query = nil, **options, &block)
       self.class.define_column(columns_array, name, query, **options, &block)
@@ -578,7 +574,6 @@ module Datagrid
 
     # @return [Array<Datagrid::Columns::Column>] all columns
     #   that are possible to be displayed for the current grid object
-    #
     # @example
     #   class MyGrid
     #     filter(:search) {|scope, value| scope.full_text_search(value)}
@@ -600,6 +595,8 @@ module Datagrid
       end
     end
 
+    # @param [String,Symbol] column_name column name
+    # @param [Object] asset one of the assets from grid scope
     # @return [Object] a cell data value for given column name and asset
     def data_value(column_name, asset)
       column = column_by_name(column_name)
@@ -611,6 +608,9 @@ module Datagrid
       end
     end
 
+    # @param [String,Symbol] column_name column name
+    # @param [Object] asset one of the assets from grid scope
+    # @param [ActionView::Base] context view context object
     # @return [Object] a cell HTML value for given column name and asset and view context
     def html_value(column_name, context, asset)
       column = column_by_name(column_name)
@@ -624,6 +624,7 @@ module Datagrid
       end
     end
 
+    # @param [Object] model one of the assets from grid scope
     # @return [Object] a decorated version of given model if decorator is specified or the model otherwise.
     def decorate(model)
       self.class.decorate(model)

data/lib/datagrid/configuration.rb

@@ -1,6 +1,20 @@
 # frozen_string_literal: true
 
 module Datagrid
+  # @return [Configuration] current Datagrid configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # @yield block to configure
+  # @yieldparam [Configuration] configuration
+  # @yieldreturn [void]
+  # @return [void] configure datagrid
+  # @see Datagrid::Configuration
+  def self.configure(&block)
+    block.call(configuration)
+  end
+
   # ## Configuration
   #
   # Datagrid provides several configuration options.
@@ -11,12 +25,14 @@ module Datagrid
   # Datagrid.configure do |config|
   #   # Defines date formats that can be used to parse dates.
   #   # Note: Multiple formats can be specified. The first format is used to format dates as strings,
-  #   # while other formats are used only for parsing dates from strings (e.g., if your app supports multiple formats).
-  #   config.date_formats = ["%m/%d/%Y", "%Y-%m-%d"]
+  #   # while other formats are used only for parsing dates
+  #   # from strings (e.g., if your app supports multiple formats).
+  #   config.date_formats = "%m/%d/%Y", "%Y-%m-%d"
   #
   #   # Defines timestamp formats that can be used to parse timestamps.
   #   # Note: Multiple formats can be specified. The first format is used to format timestamps as strings,
-  #   # while other formats are used only for parsing timestamps from strings (e.g., if your app supports multiple formats).
+  #   # while other formats are used only for parsing timestamps
+  #   # from strings (e.g., if your app supports multiple formats).
   #   config.datetime_formats = ["%m/%d/%Y %h:%M", "%Y-%m-%d %h:%M:%s"]
   # end
   # ```

data/lib/datagrid/filters/base_filter.rb

@@ -7,7 +7,6 @@ module Datagrid
   end
 end
 
-# @!visibility private
 module Datagrid
   module Filters
     class BaseFilter

data/lib/datagrid/filters/extended_boolean_filter.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# @!visibility private
 module Datagrid
   module Filters
     class ExtendedBooleanFilter < Datagrid::Filters::EnumFilter

data/lib/datagrid/filters/float_filter.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# @!visibility private
 module Datagrid
   module Filters
     class FloatFilter < Datagrid::Filters::BaseFilter

data/lib/datagrid/filters.rb

@@ -161,7 +161,6 @@ module Datagrid
 
     extend ActiveSupport::Concern
 
-    # @!visibility private
     included do
       include Datagrid::Core
       class_attribute :filters_array, default: []
@@ -192,35 +191,28 @@ module Datagrid
       # @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

data/lib/datagrid/generators/scaffold.rb

@@ -2,7 +2,6 @@
 
 require "rails/generators"
 
-# @!visibility private
 module Datagrid
   # @!visibility private
   module Generators

data/lib/datagrid/helper.rb

@@ -17,7 +17,8 @@ module Datagrid
   # [built-in CSS](https://github.com/bogdan/datagrid/blob/master/app/assets/stylesheets/datagrid.sass).
   #
   # Datagrid includes helpers and a form builder for easy frontend generation.
-  # If you need a fully-featured custom GUI, create your templates manually with the help of the {Datagrid::Columns} API.
+  # If you need a fully-featured custom GUI, create your templates manually
+  # with the help of the {Datagrid::Columns} API.
   #
   # ## Controller and Routing
   #
@@ -63,7 +64,8 @@ module Datagrid
   #
   # ### Advanced Method
   #
-  # You can use Rails built-in tools to create a form. Additionally, Datagrid provides helpers to generate input/select elements for filters:
+  # You can use Rails built-in tools to create a form.
+  # Additionally, Datagrid provides helpers to generate input/select elements for filters:
   #
   # ``` haml
   # - form_with model: UserGrid.new, method: :get, url: users_path do |f|
@@ -240,7 +242,7 @@ module Datagrid
   #
   # https://github.com/bogdan/datagrid/blob/master/lib/datagrid/locale/en.yml
   module Helper
-    # @param grid [Datagrid] grid object
+    # @param grid [Datagrid::Base] grid object
     # @param column [Datagrid::Columns::Column, String, Symbol] column name
     # @param model [Object] an object from grid scope
     # @return [Object] individual cell value from the given grid, column name and model
@@ -264,19 +266,16 @@ module Datagrid
     # 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 grid [Datagrid::Base] 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,16 +293,14 @@ module Datagrid
 
     # 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'.
-    # @param grid [Datagrid] grid object
+    # @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::Base] grid object
     # @param [Object] opts (deprecated) pass keyword arguments instead
     # @param [Hash] options
     # @return [String] HTML table header tag markup
@@ -321,22 +318,21 @@ module Datagrid
     # 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
+    # @param [Datagrid::Base] grid datagrid object
+    # @param [Array<Object>] assets assets as per defined in grid scope
     def datagrid_rows(grid, assets = grid.assets, **options, &block)
       safe_join(
         assets.map do |asset|
@@ -346,11 +342,12 @@ module Datagrid
     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'`.
+    # @param [Datagrid::Base] grid datagrid object
+    # @param [Datagrid::Columns::Column] column
+    # @deprecated Put necessary code inline inside datagrid/head partial.
+    #   See built-in partial for example.
     def datagrid_order_for(grid, column, options = {})
       Datagrid::Utils.warn_once(<<~MSG)
         datagrid_order_for is deprecated.
@@ -362,15 +359,11 @@ module Datagrid
     end
 
     # Renders HTML for grid with all filters inputs and labels defined in it
-    #
-    # Supported options:
-    #
-    # * <tt>:partials</tt> - Path for form partial lookup.
-    #   Default: 'datagrid' results in using `app/views/datagrid/` partials.
-    #   Example: 'datagrid_admin' results in using `app/views/datagrid_admin` partials.
-    # * <tt>:model</tt> - Datagrid object to be rendedred.
-    # * All options supported by Rails <tt>form_with</tt> helper
-    # @param grid [Datagrid] grid object
+    # @option options [String] partials Path for form partial lookup.
+    #   Default: `'datagrid'`, which uses `app/views/datagrid/` partials.
+    #   Example: `'datagrid_admin'` uses `app/views/datagrid_admin` partials.
+    # @option options [Datagrid::Base] model a Datagrid object to be rendered.
+    # @option options [Hash] All options supported by Rails `form_with` helper.
     # @param [Hash{Symbol => Object}] options
     # @return [String] form HTML tag markup
     def datagrid_form_with(**options)
@@ -390,7 +383,7 @@ module Datagrid
     #   Default: 'datagrid'.
     # * All options supported by Rails <tt>form_with</tt> helper
     # @deprecated Use {#datagrid_form_with} instead.
-    # @param grid [Datagrid] grid object
+    # @param grid [Datagrid::Base] grid object
     # @param [Hash] options
     # @return [String] form HTML tag markup
     def datagrid_form_for(grid, options = {})
@@ -409,25 +402,24 @@ module Datagrid
 
     # Provides access to datagrid columns data.
     # Used in case you want to build html table completelly manually
-    # @param grid [Datagrid] grid object
+    # @param grid [Datagrid::Base] grid object
     # @param asset [Object] object from grid scope
     # @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?
@@ -435,7 +427,7 @@ module Datagrid
     end
 
     # Generates an ascending or descending order url for the given column
-    # @param grid [Datagrid] grid object
+    # @param grid [Datagrid::Base] grid object
     # @param column [Datagrid::Columns::Column, String, Symbol] column name
     # @param descending [Boolean] order direction, descending if true, otherwise ascending.
     # @return [String] order layout HTML markup
@@ -475,7 +467,7 @@ module Datagrid
     #   row = datagrid_row(grid, user)
     #   row.class      # => Datagrid::Helper::HtmlRow
     #   row.first_name # => "<strong>Bogdan</strong>"
-    #   row.grid       # => Grid object
+    #   row.grid       # => Datagrid::Base object
     #   row.asset      # => User object
     #   row.each do |value|
     #     puts value

data/lib/datagrid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Datagrid
-  VERSION = "2.0.0-alpha"
+  VERSION = "2.0.0"
 end

data/lib/datagrid.rb

@@ -4,7 +4,6 @@ require "action_view"
 require "datagrid/configuration"
 require "datagrid/engine"
 
-# @main README.md
 module Datagrid
   # @!visibility private
   def self.included(base)
@@ -19,15 +18,6 @@ module Datagrid
     end
   end
 
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
-
-  # Configure
-  def self.configure(&block)
-    block.call(configuration)
-  end
-
   class ConfigurationError < StandardError; end
   class ArgumentError < ::ArgumentError; end
   class ColumnUnavailableError < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: datagrid
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.alpha
+  version: 2.0.0
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-19 00:00:00.000000000 Z
+date: 2024-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -33,6 +33,7 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -93,7 +94,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/bogdan/datagrid
   bug_tracker_uri: https://github.com/bogdan/datagrid/issues
-  documentation_uri: https://github.com/bogdan/datagrid/wiki
+  documentation_uri: https://rubydoc.info/gems/datagrid
   changelog_uri: https://github.com/bogdan/datagrid/blob/main/CHANGELOG.md
   source_code_uri: https://github.com/bogdan/datagrid
   rubygems_mfa_required: 'true'