iron_admin 0.5.0 → 0.6.0

data/lib/iron_admin/dashboard.rb

@@ -66,11 +66,12 @@ module IronAdmin
       #   - :number - Plain number with thousands separators
       #   - :currency - Currency format (uses Rails number_to_currency)
       #   - :percentage - Percentage format
+      # @param icon [String, nil] Optional Heroicon name for visual context (e.g., "users", "currency-dollar")
       # @yield Block that computes and returns the metric value
       # @yieldreturn [Numeric] The metric value
       #
-      # @example User count metric
-      #   metric :total_users, format: :number do
+      # @example User count metric with icon
+      #   metric :total_users, format: :number, icon: "users" do
       #     User.count
       #   end
       #
@@ -79,14 +80,9 @@ module IronAdmin
       #     Order.where(status: "completed").sum(:total)
       #   end
       #
-      # @example Conversion rate metric
-      #   metric :conversion_rate, format: :percentage do
-      #     (Order.count.to_f / Visit.count * 100).round(1)
-      #   end
-      #
       # @return [void]
-      def metric(name, format: :number, &block)
-        self.defined_metrics = defined_metrics + [{ name: name, format: format, block: block }]
+      def metric(name, format: :number, icon: nil, live: false, &block)
+        self.defined_metrics = defined_metrics + [{ name: name, format: format, icon: icon, live: live, block: block }]
       end
 
       # Defines a chart for the dashboard.
@@ -94,7 +90,7 @@ module IronAdmin
       # Charts display time-series or categorical data visually.
       # The block should return data in a format suitable for the chart type.
       #
-      # @param name [Symbol] The chart identifier (used as the chart title)
+      # @param name [Symbol] The chart identifier
       # @param type [Symbol] The chart type
       #   - :line - Line chart for trends over time
       #   - :bar - Bar chart for comparisons
@@ -102,12 +98,14 @@ module IronAdmin
       #   - :doughnut - Doughnut chart for proportions
       # @param colors [Array<String>, nil] Optional per-chart color palette (CSS color values).
       #   Overrides the global theme chart_colors for this chart.
+      # @param label [String, nil] Custom display title for the chart.
+      #   Defaults to `name.to_s.humanize` when not provided.
       # @yield Block that computes and returns the chart data
       # @yieldreturn [Hash, Array] Data for the chart (format depends on type)
       #
-      # @example Line chart of signups over time
-      #   chart :signups_by_month, type: :line do
-      #     User.group_by_month(:created_at).count
+      # @example Chart with custom label
+      #   chart :projects_by_status, type: :bar, label: "Projects by Status" do
+      #     Project.group(:status).count
       #   end
       #
       # @example Bar chart with custom colors
@@ -115,14 +113,11 @@ module IronAdmin
       #     Order.group(:status).count
       #   end
       #
-      # @example Pie chart of users by role
-      #   chart :users_by_role, type: :pie do
-      #     User.group(:role).count
-      #   end
-      #
       # @return [void]
-      def chart(name, type: :line, colors: nil, &block)
-        self.defined_charts = defined_charts + [{ name: name, type: type, colors: colors, block: block }]
+      def chart(name, type: :line, colors: nil, label: nil, live: false, &block)
+        self.defined_charts = defined_charts + [
+          { name: name, type: type, colors: colors, label: label, live: live, block: block },
+        ]
       end
 
       # Displays a list of recent records from a resource.

data/lib/iron_admin/engine.rb

@@ -24,7 +24,15 @@ module IronAdmin
 
     initializer "iron_admin.assets" do |app|
       if app.config.respond_to?(:assets) && app.config.assets
-        app.config.assets.precompile += %w[iron_admin_manifest]
+        # `app/assets/config/iron_admin_manifest.js` is a Sprockets manifest
+        # that link_trees the engine's JavaScript bundle. Adding it to
+        # `precompile` recursively pulls in `app/javascript/iron_admin/**/*.js`,
+        # which is what the layout references via `javascript_importmap_tags`
+        # (importmap pin: `iron_admin/index.js`). Without this entry, hosts on
+        # sprockets-rails (Rails 7.1 default) get
+        # `Asset 'iron_admin/index.js' was not declared to be precompiled`
+        # on every resource page.
+        app.config.assets.precompile += %w[iron_admin_manifest.js]
         app.config.assets.paths << root.join("vendor/assets/javascripts")
         app.config.assets.paths << root.join("app/javascript")
       end
@@ -38,6 +46,19 @@ module IronAdmin
       config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.yml")]
     end
 
+    # Expose `heroicon` directly on every ViewComponent instance.
+    # ViewComponent does not auto-include host-app `ApplicationHelper`
+    # methods on component templates, so calling `heroicon "users"` from
+    # a HAML template would otherwise raise `NoMethodError` (depending on
+    # ViewComponent version). Including the helper module on
+    # `ViewComponent::Base` makes `heroicon` available to every component
+    # template and Ruby method without requiring `helpers.heroicon`.
+    initializer "iron_admin.view_component_heroicon" do
+      ActiveSupport.on_load(:view_component) do
+        include Heroicon::ApplicationHelper
+      end
+    end
+
     initializer "iron_admin.autoload", before: :set_autoload_paths do
       resource_path = Rails.root.join("app/iron_admin")
       Rails.autoloaders.main.push_dir(resource_path, namespace: IronAdmin) if resource_path.exist?
@@ -48,6 +69,12 @@ module IronAdmin
       if resource_path.exist?
         IronAdmin::ResourceRegistry.reset!
         Rails.autoloaders.main.eager_load_dir(resource_path)
+        # Eager-loading runs each resource's `inherited` hook, which adds
+        # the class to the registry. Now that every class body has fully
+        # evaluated (and thus `self.adapter_class = :mongoid` etc. have
+        # taken effect), call `finalize!` to run the model introspection
+        # steps (soft-delete features, etc.) with the correct adapter.
+        IronAdmin::ResourceRegistry.finalize!
       end
     end
   end

data/lib/iron_admin/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  # Base error class for all IronAdmin errors.
+  class Error < StandardError; end
+
+  # Raised when a record cannot be found by ID.
+  # Adapter-agnostic replacement for ActiveRecord::RecordNotFound.
+  class RecordNotFound < Error; end
+
+  # Raised inside a transaction block to trigger a rollback.
+  # Adapter-agnostic replacement for ActiveRecord::Rollback.
+  class Rollback < Error; end
+
+  # Raised when an adapter encounters an operational error
+  # (network failure, invalid response, etc.).
+  class AdapterError < Error; end
+
+  # Exception classes that mean the database is missing or unreachable
+  # at boot time. Resolved lazily so the gem stays usable on
+  # `--skip-active-record` hosts where `ActiveRecord` isn't loaded.
+  #
+  # @return [Array<Class>] Rescue classes for boot-time DB failures
+  def self.db_unreachable_exceptions
+    return [] unless defined?(ActiveRecord)
+
+    [ActiveRecord::NoDatabaseError, ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished]
+  end
+end

data/lib/iron_admin/field_inferrer.rb

@@ -44,33 +44,42 @@ module IronAdmin
       jsonb: :json,
     }.freeze
 
-    # Infers fields for a model.
+    # Infers fields for a model or adapter.
     #
-    # @param model [Class] An ActiveRecord model class
+    # @param model_or_adapter [Class, IronAdmin::Adapters::Base] An ActiveRecord model class or adapter instance
     # @return [Array<IronAdmin::Field>] Inferred field objects
     #
-    # @example
+    # @example With a model (backward compatible)
     #   fields = IronAdmin::FieldInferrer.call(User)
-    def self.call(model)
-      new(model).call
+    #
+    # @example With an adapter (preferred)
+    #   fields = IronAdmin::FieldInferrer.call(resource.adapter)
+    def self.call(model_or_adapter)
+      adapter = if model_or_adapter.is_a?(IronAdmin::Adapters::Base)
+                  model_or_adapter
+                else
+                  IronAdmin::Adapters::ActiveRecord.new(model_or_adapter)
+                end
+      new(adapter).call
     end
 
-    # Creates a new FieldInferrer for the given model.
+    # Creates a new FieldInferrer for the given adapter.
     #
-    # @param model [Class] An ActiveRecord model class
-    def initialize(model)
-      @model = model
-      @polymorphic_map = model.reflect_on_all_associations(:belongs_to)
+    # @param adapter [IronAdmin::Adapters::Base] An adapter instance
+    def initialize(adapter)
+      @adapter = adapter
+      @polymorphic_map = adapter.associations(:belongs_to)
         .select(&:polymorphic?)
         .index_by { |a| a.name.to_s }
       @polymorphic_columns = @polymorphic_map.values
         .flat_map { |a| [a.foreign_type, a.foreign_key.to_s] }.to_set
-      @belongs_to_map = model.reflect_on_all_associations(:belongs_to)
+      @belongs_to_map = adapter.associations(:belongs_to)
         .reject(&:polymorphic?)
         .index_by { |a| a.foreign_key.to_s }
-      @shadowed_columns = model.reflect_on_all_associations(:has_many)
-        .concat(model.reflect_on_all_associations(:has_one))
+      @shadowed_columns = adapter.associations(:has_many)
+        .concat(adapter.associations(:has_one))
         .to_set { |a| a.name.to_s }
+      @polymorphic_types_map = build_polymorphic_types_map
     end
 
     # Infers fields from the model's columns, associations, attachments,
@@ -84,7 +93,7 @@ module IronAdmin
     #
     # @return [Array<IronAdmin::Field>] Inferred field objects
     def call
-      fields = @model.columns.filter_map do |column|
+      fields = @adapter.columns.filter_map do |column|
         next if @shadowed_columns.include?(column.name)
         next if @polymorphic_columns.include?(column.name)
 
@@ -110,7 +119,7 @@ module IronAdmin
       name = column.name.to_sym
 
       if enum_column?(name)
-        Field.new(name, type: :select, choices: @model.defined_enums[name.to_s].keys)
+        Field.new(name, type: :select, choices: @adapter.enums[name.to_s].keys)
       else
         type = infer_type(column)
         Field.new(name, type: type)
@@ -134,7 +143,12 @@ module IronAdmin
     end
 
     # @api private
-    # Builds fields for polymorphic belongs_to associations.
+    # Builds fields for polymorphic belongs_to associations. Auto-infers the
+    # valid target types by scanning all `ApplicationRecord` descendants for
+    # `has_many :<name>, as: :<polymorphic_name>` and
+    # `has_one :<name>, as: :<polymorphic_name>` declarations. Without this,
+    # the form's type `<select>` is empty and the polymorphic association is
+    # unusable in the admin (see #79).
     def polymorphic_fields
       @polymorphic_map.map do |name, assoc|
         Field.new(
@@ -142,11 +156,34 @@ module IronAdmin
           type: :polymorphic_belongs_to,
           association_name: name.to_sym,
           type_column: assoc.foreign_type.to_sym,
-          id_column: assoc.foreign_key.to_sym
+          id_column: assoc.foreign_key.to_sym,
+          types: infer_polymorphic_types(name.to_sym)
         )
       end
     end
 
+    # @api private
+    # Returns the model classes that declare `has_many` / `has_one` with
+    # `as: <polymorphic_name>` — i.e. the valid targets for a polymorphic
+    # `belongs_to :<polymorphic_name>`.
+    #
+    # @param polymorphic_name [Symbol] e.g. `:notable`
+    # @return [Array<Class>]
+    def infer_polymorphic_types(polymorphic_name)
+      @polymorphic_types_map[polymorphic_name] || []
+    end
+
+    # @api private
+    # Builds `{ polymorphic_name => [target_classes] }` once per inferrer.
+    # Each adapter owns model discovery because ActiveRecord and Mongoid load
+    # model classes differently.
+    def build_polymorphic_types_map
+      return {} if @polymorphic_map.empty?
+
+      needed = @polymorphic_map.keys.to_set(&:to_sym)
+      needed.index_with { |name| @adapter.polymorphic_inverse_classes(name) }
+    end
+
     # @api private
     # Builds a belongs_to field from an association reflection.
     def build_belongs_to_field(association)
@@ -162,15 +199,16 @@ module IronAdmin
     # @api private
     # Checks if a column is backed by an enum.
     def enum_column?(name)
-      @model.defined_enums.key?(name.to_s)
+      @adapter.enums.key?(name.to_s)
     end
 
     # @api private
     # Builds fields for ActiveStorage attachments (has_one_attached / has_many_attached).
     def attachment_fields
-      return [] unless @model.respond_to?(:attachment_reflections)
+      attachments = @adapter.attachments
+      return [] if attachments.empty?
 
-      @model.attachment_reflections.map do |name, reflection|
+      attachments.map do |name, reflection|
         type = reflection.macro == :has_one_attached ? :file : :files
         Field.new(name.to_sym, type: type)
       end
@@ -179,9 +217,10 @@ module IronAdmin
     # @api private
     # Builds fields for ActionText rich text attributes (has_rich_text).
     def rich_text_fields
-      return [] unless @model.respond_to?(:rich_text_association_names)
+      rich_text_attrs = @adapter.rich_text_attributes
+      return [] if rich_text_attrs.empty?
 
-      @model.rich_text_association_names.map do |assoc_name|
+      rich_text_attrs.map do |assoc_name|
         # ActionText associations are named like "rich_text_body" — strip the prefix
         attr_name = assoc_name.to_s.delete_prefix("rich_text_").to_sym
         Field.new(attr_name, type: :rich_text)

data/lib/iron_admin/filters/active_record_query_builder.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Filters
+    # ActiveRecord-specific query builder for operator-based filters.
+    # Uses SQL LIKE/ILIKE for string ops and parameterized queries for number ops.
+    class ActiveRecordQueryBuilder < BaseQueryBuilder
+      private
+
+      def apply_string_filter
+        return @scope unless STRING_OPS.include?(@op)
+
+        col = quoted_column
+        like_op = postgres? ? "ILIKE" : "LIKE"
+        escape = "ESCAPE '\\'"
+
+        case @op
+        when "contains"    then @scope.where("#{col} #{like_op} ? #{escape}", "%#{sanitize_like(@value)}%")
+        when "equals"      then @scope.where(@filter[:name] => @value)
+        when "starts_with" then @scope.where("#{col} #{like_op} ? #{escape}", "#{sanitize_like(@value)}%")
+        when "ends_with"   then @scope.where("#{col} #{like_op} ? #{escape}", "%#{sanitize_like(@value)}")
+        else @scope
+        end
+      end
+
+      def apply_number_filter
+        return @scope unless NUMBER_OPS.include?(@op)
+
+        num = cast_number(@value)
+        return @scope unless num
+
+        case @op
+        when "equals"       then @scope.where(@filter[:name] => num)
+        when "greater_than" then @scope.where("#{quoted_column} > ?", num)
+        when "less_than"    then @scope.where("#{quoted_column} < ?", num)
+        when "between"      then apply_between_filter(num)
+        else @scope
+        end
+      end
+
+      def apply_between_filter(num)
+        upper_num = cast_number(@upper_value)
+        return @scope unless upper_num
+
+        @scope.where(@filter[:name] => num..upper_num)
+      end
+
+      def quoted_column
+        conn = @scope.connection
+        table = conn.quote_table_name(@scope.model.table_name)
+        "#{table}.#{conn.quote_column_name(@filter[:name])}"
+      end
+
+      def sanitize_like(value)
+        value.gsub(/[%_\\]/) { |m| "\\#{m}" }
+      end
+
+      def postgres?
+        @scope.connection.adapter_name.match?(/PostgreSQL/i)
+      end
+    end
+  end
+end

data/lib/iron_admin/filters/base_query_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Filters
+    # Abstract base class for operator-based filter query builders.
+    #
+    # Subclasses implement the adapter-specific query building for string
+    # and number filter operators. ActiveRecord uses SQL LIKE/ILIKE,
+    # Mongoid uses $regex and comparison operators.
+    class BaseQueryBuilder
+      STRING_OPS = %w[contains equals starts_with ends_with].freeze
+      NUMBER_OPS = %w[equals greater_than less_than between].freeze
+
+      def self.call(scope, filter, params_hash)
+        new(scope, filter, params_hash).call
+      end
+
+      def initialize(scope, filter, params_hash)
+        @scope = scope
+        @filter = filter
+        @op = params_hash["op"].to_s
+        @value = params_hash["value"].to_s.strip
+        @upper_value = params_hash["value_2"].to_s.strip
+      end
+
+      def call
+        return @scope if @value.blank?
+
+        case @filter[:type]
+        when :string then apply_string_filter
+        when :number then apply_number_filter
+        else @scope
+        end
+      end
+
+      private
+
+      def apply_string_filter
+        raise NotImplementedError
+      end
+
+      def apply_number_filter
+        raise NotImplementedError
+      end
+
+      def cast_number(val)
+        return nil if val.blank?
+
+        val.include?(".") ? Float(val) : Integer(val)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/iron_admin/filters/http_query_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Filters
+    # HTTP-specific query builder for operator-based filters.
+    # Translates string and number operators to query parameters
+    # that are sent to the remote API.
+    class HttpQueryBuilder < BaseQueryBuilder
+      private
+
+      def apply_string_filter
+        return @scope unless STRING_OPS.include?(@op)
+
+        field = @filter[:name].to_s
+        @scope.where("#{field}[#{@op}]" => @value)
+      end
+
+      def apply_number_filter
+        return @scope unless NUMBER_OPS.include?(@op)
+
+        num = cast_number(@value)
+        return @scope unless num
+
+        field = @filter[:name].to_s
+        case @op
+        when "between" then apply_between_filter(field, num)
+        else @scope.where("#{field}[#{@op}]" => num)
+        end
+      end
+
+      def apply_between_filter(field, num)
+        upper_num = cast_number(@upper_value)
+        return @scope unless upper_num
+
+        @scope.where("#{field}[gte]" => num, "#{field}[lte]" => upper_num)
+      end
+    end
+  end
+end

data/lib/iron_admin/filters/mongoid_query_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Filters
+    # Mongoid-specific query builder for operator-based filters.
+    # Uses MongoDB $regex for string ops and comparison operators for number ops.
+    class MongoidQueryBuilder < BaseQueryBuilder
+      BSON_INT64_RANGE = (-9_223_372_036_854_775_808..9_223_372_036_854_775_807)
+      private_constant :BSON_INT64_RANGE
+
+      private
+
+      def apply_string_filter
+        return @scope unless STRING_OPS.include?(@op)
+
+        case @op
+        when "contains"    then @scope.where(@filter[:name] => /#{Regexp.escape(@value)}/i)
+        when "equals"      then @scope.where(@filter[:name] => @value)
+        when "starts_with" then @scope.where(@filter[:name] => /\A#{Regexp.escape(@value)}/i)
+        when "ends_with"   then @scope.where(@filter[:name] => /#{Regexp.escape(@value)}\z/i)
+        else @scope
+        end
+      end
+
+      def apply_number_filter
+        return @scope unless NUMBER_OPS.include?(@op)
+
+        num = cast_number(@value)
+        return @scope unless num
+
+        field = @filter[:name].to_s
+        case @op
+        when "equals"       then @scope.where(field => num)
+        when "greater_than" then @scope.where(field => { "$gt" => num })
+        when "less_than"    then @scope.where(field => { "$lt" => num })
+        when "between"      then apply_between_filter(field, num)
+        else @scope
+        end
+      end
+
+      def apply_between_filter(field, num)
+        upper_num = cast_number(@upper_value)
+        return @scope unless upper_num
+
+        @scope.where(field => { "$gte" => num, "$lte" => upper_num })
+      end
+
+      def cast_number(val)
+        number = super
+        return unless number
+        return number unless number.is_a?(Integer)
+        return number if BSON_INT64_RANGE.cover?(number)
+
+        nil
+      end
+    end
+  end
+end

data/lib/iron_admin/filters/query_builder.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "base_query_builder"
+require_relative "active_record_query_builder"
+
+module IronAdmin
+  module Filters
+    # Backward-compatible alias for ActiveRecordQueryBuilder.
+    # @deprecated Use {ActiveRecordQueryBuilder} directly.
+    QueryBuilder = ActiveRecordQueryBuilder
+  end
+end

data/lib/iron_admin/import/column_mapper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Import
+    class ColumnMapper
+      def initialize(resource_class, current_user: nil)
+        @resource_class = resource_class
+        @current_user = current_user
+      end
+
+      def map_headers(headers)
+        candidates = field_candidates
+
+        headers.each_with_object({}) do |header, mapping|
+          field = candidates[normalize(header)]
+          mapping[header] = field.name if field
+        end
+      end
+
+      private
+
+      def field_candidates
+        @resource_class.importable_fields(@current_user).each_with_object({}) do |field, candidates|
+          candidate_labels(field).each { |label| candidates[normalize(label)] = field }
+        end
+      end
+
+      def candidate_labels(field)
+        [
+          field.name,
+          field.name.to_s,
+          field.name.to_s.humanize,
+          field.options[:label],
+        ].compact
+      end
+
+      def normalize(value)
+        value.to_s.downcase.gsub(/[^a-z0-9]/, "")
+      end
+    end
+  end
+end

data/lib/iron_admin/import/import_preview.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Import
+    Row = Struct.new(:number, :attributes, :errors, keyword_init: true) unless const_defined?(:Row)
+    Error = Struct.new(:row_number, :message, keyword_init: true) unless const_defined?(:Error)
+
+    ImportPreview = Struct.new(:total_rows, :headers, :mapping, :rows, :errors, keyword_init: true)
+  end
+end

data/lib/iron_admin/import/import_result.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Import
+    Row = Struct.new(:number, :attributes, :errors, keyword_init: true) unless const_defined?(:Row)
+    Error = Struct.new(:row_number, :message, keyword_init: true) unless const_defined?(:Error)
+
+    ImportResult = Struct.new(:created_count, :updated_count, :failed_count, :errors, :rows, keyword_init: true)
+  end
+end