iron_admin 0.4.1 → 0.6.0

data/lib/iron_admin/resource.rb

@@ -40,6 +40,11 @@ module IronAdmin
   # @see IronAdmin::Field For field configuration options
   # @see IronAdmin::Policy For authorization options
   class Resource
+    include Concerns::Nestable
+    include Concerns::SoftDeletable
+    include Concerns::Importable
+    include Concerns::LiveUpdatable
+
     class_attribute :field_overrides, default: {}
     class_attribute :_searchable_columns, default: nil
     class_attribute :_unsearchable_columns, default: []
@@ -57,6 +62,7 @@ module IronAdmin
     class_attribute :denied_crud_actions, default: []
     class_attribute :defined_associations, default: {}
     class_attribute :model_class_override, default: nil
+    class_attribute :adapter_class, default: :active_record
     class_attribute :_soft_delete_scopes, default: []
 
     class << self
@@ -72,6 +78,25 @@ module IronAdmin
         end
       end
 
+      # Returns the adapter instance for this resource's model.
+      #
+      # The adapter provides a uniform interface for schema introspection,
+      # query building, and CRUD operations regardless of the underlying
+      # data source (ActiveRecord, Mongoid, HTTP, etc.).
+      #
+      # Defensively re-resolves when the cached `@adapter` doesn't match
+      # the currently configured `adapter_class`. This catches the case
+      # where the eager `Resource.inherited` flow memoized an
+      # `Adapters::ActiveRecord` built before the subclass body's
+      # `self.adapter_class = :mongoid` (or `:http`) took effect.
+      #
+      # @return [IronAdmin::Adapters::Base] The adapter instance
+      def adapter
+        wanted = resolve_adapter_class
+        @adapter = nil if @adapter && !@adapter.instance_of?(wanted)
+        @adapter ||= wanted.new(model)
+      end
+
       # Returns the ActiveRecord model class for this resource.
       #
       # By default, infers the model from the resource class name
@@ -83,10 +108,19 @@ module IronAdmin
       #   class LegacyUserResource < IronAdmin::Resource
       #     self.model_class_override = OldUser
       #   end
+      #
+      # @example HTTP adapter — no Ruby model required
+      #   class ProductResource < IronAdmin::Resource
+      #     self.adapter_class = :http
+      #     # `model` returns `Adapters::Http::ModelProxy.new(self)` — no
+      #     # `Product` constant required; fields come from the API
+      #     # response on first access.
+      #   end
       def model
         return model_class_override if model_class_override
+        return Adapters::Http::ModelProxy.new(self) if adapter_class == :http
 
-        name.sub(/Resource\z/, "").constantize
+        name.sub(/Resource\z/, "").sub(/\AIronAdmin::Resources::/, "").constantize
       end
 
       # Configures display and behavior options for a field.
@@ -162,7 +196,7 @@ module IronAdmin
       def searchable_columns
         return _searchable_columns if _searchable_columns
 
-        model.columns.select { |c| c.type.in?(%i[string text]) }
+        adapter.columns.select { |c| c.type.in?(%i[string text]) }
           .map { |c| c.name.to_sym }
           .reject { |name| name.to_s.end_with?("_digest") }
           .reject { |name| _unsearchable_columns.include?(name) }
@@ -206,19 +240,16 @@ module IronAdmin
       end
 
       # @api private
-      # Returns filters automatically inferred from enum columns.
+      # Returns filters automatically inferred from enum columns and database column types.
+      #
+      # String/text columns auto-infer as :string filters.
+      # Integer/float/decimal columns auto-infer as :number filters.
+      # Enum columns auto-infer as :select filters.
       #
       # @return [Array<Hash>] Auto-generated filter configurations
       def auto_inferred_filters
-        return [] unless model.respond_to?(:defined_enums)
-
-        model.defined_enums.map do |name, values|
-          {
-            name: name.to_sym,
-            type: :select,
-            options: values.keys,
-          }
-        end
+        enum_filters = enum_auto_filters
+        enum_filters + infer_column_filters(enum_filters)
       end
 
       # Returns all filters (auto-inferred + manually defined).
@@ -281,8 +312,9 @@ module IronAdmin
       #   end
       #
       # @return [void]
-      def action(name, **options, &block)
-        self.defined_actions = defined_actions + [{ name: name, block: block, **options }]
+      def action(name, form_fields: [], **options, &block)
+        coerced = coerce_action_fields(form_fields)
+        self.defined_actions = defined_actions + [{ name: name, block: block, form_fields: coerced, **options }]
       end
 
       # Defines a bulk action for multiple selected records.
@@ -310,8 +342,27 @@ module IronAdmin
       #   end
       #
       # @return [void]
-      def bulk_action(name, **options, &block)
-        self.defined_bulk_actions = defined_bulk_actions + [{ name: name, block: block, **options }]
+      def bulk_action(name, form_fields: [], **options, &block)
+        coerced = coerce_action_fields(form_fields)
+        self.defined_bulk_actions = defined_bulk_actions + [{ name: name, block: block, form_fields: coerced, **options }]
+      end
+
+      # Convenience constructor for ActionField instances.
+      #
+      # @param name [Symbol] The field name
+      # @param opts [Hash] Options passed to ActionField.new
+      # @return [IronAdmin::ActionField]
+      #
+      # @example
+      #   action :suspend,
+      #     form_fields: [
+      #       action_field(:reason, type: :textarea, required: true),
+      #       action_field(:notify, type: :boolean)
+      #     ] do |record, params|
+      #     # ...
+      #   end
+      def action_field(name, **)
+        ActionField.new(name: name, **)
       end
 
       # Specifies which fields appear on the index (list) page.
@@ -350,13 +401,25 @@ module IronAdmin
       # @option options [String] :icon Heroicon name for the menu item
       # @option options [String] :label Custom label (defaults to pluralized model name)
       # @option options [Integer] :priority Sort order (lower = higher in menu)
-      # @option options [String] :section Group name for menu sections
+      # @option options [String] :group Group name for the sidebar section
+      #   (sibling resources sharing the same `:group` are listed together;
+      #   resources without a `:group` fall under "Resources"). `:section`
+      #   is also accepted as an alias for `:group` for backward
+      #   compatibility with earlier docs.
       #
       # @example
-      #   menu icon: "users", label: "Team Members", priority: 10
+      #   menu icon: "users", label: "Team Members", priority: 10, group: "People"
       #
       # @return [void]
       def menu(**options)
+        if options.key?(:section)
+          legacy = options.delete(:section)
+          # Preserve `:group` precedence based on key presence so that
+          # explicitly passing `group: nil` (or `group: false`) still
+          # wins over `section:`. Using `||=` would clobber falsey
+          # explicit values.
+          options[:group] = legacy unless options.key?(:group)
+        end
         self.menu_options = options
       end
 
@@ -498,24 +561,7 @@ module IronAdmin
       #   has_many :orders
       #   has_many :comments, fields: [:id, :body, :created_at]
       #
-      # @return [void]
-      def has_many(name, **options)
-        self.defined_associations = defined_associations.merge(name => { kind: :has_many, **options })
-      end
-
-      # Declares a has_one association for this resource.
-      #
-      # @param name [Symbol] The association name
-      # @param options [Hash] Configuration options
-      # @option options [Class] :resource The associated resource class
-      #
-      # @example
-      #   has_one :profile
-      #
-      # @return [void]
-      def has_one(name, **options)
-        self.defined_associations = defined_associations.merge(name => { kind: :has_one, **options })
-      end
+      # has_many and has_one are defined in Concerns::Nestable
 
       # Declares a has_and_belongs_to_many association for this resource.
       #
@@ -541,7 +587,7 @@ module IronAdmin
       #
       # @return [Array<IronAdmin::Field>] Configured field objects
       def resolved_fields
-        inferred = FieldInferrer.call(model)
+        inferred = FieldInferrer.call(adapter)
 
         inferred.map do |field|
           overrides = field_overrides[field.name] || {}
@@ -587,13 +633,13 @@ module IronAdmin
         defined_associations.filter_map do |assoc_name, config|
           next unless config[:kind] == :has_many
 
-          reflection = model.reflect_on_association(assoc_name)
+          reflection = adapter.association(assoc_name)
           next unless reflection
 
-          resource = ResourceRegistry.find(reflection.klass.model_name.plural)
+          resource = resolve_association_resource(config, reflection)
           next unless resource
 
-          { name: assoc_name, reflection: reflection, resource: resource, **config.except(:kind) }
+          { name: assoc_name, reflection: reflection, resource: resource, **config.except(:kind, :resource) }
         end
       end
 
@@ -604,13 +650,13 @@ module IronAdmin
         defined_associations.filter_map do |assoc_name, config|
           next unless config[:kind] == :has_one
 
-          reflection = model.reflect_on_association(assoc_name)
+          reflection = adapter.association(assoc_name)
           next unless reflection
 
-          resource = ResourceRegistry.find(reflection.klass.model_name.plural)
+          resource = resolve_association_resource(config, reflection)
           next unless resource
 
-          { name: assoc_name, reflection: reflection, resource: resource, **config.except(:kind) }
+          { name: assoc_name, reflection: reflection, resource: resource, **config.except(:kind, :resource) }
         end
       end
 
@@ -621,27 +667,25 @@ module IronAdmin
         defined_associations.filter_map do |assoc_name, config|
           next unless config[:kind] == :has_and_belongs_to_many
 
-          reflection = model.reflect_on_association(assoc_name)
+          reflection = adapter.association(assoc_name)
           next unless reflection
 
-          resource = ResourceRegistry.find(reflection.klass.model_name.plural)
+          resource = resolve_association_resource(config, reflection)
 
-          { name: assoc_name, reflection: reflection, resource: resource, **config.except(:kind) }
+          { name: assoc_name, reflection: reflection, resource: resource, **config.except(:kind, :resource) }
         end
       end
 
       # Returns the URL-friendly resource name (pluralized model name).
       #
       # @return [String] The resource name (e.g., "users", "orders")
-      def resource_name
-        model.model_name.plural
-      end
+      delegate :resource_name, to: :adapter
 
       # Returns the human-readable label for this resource.
       #
       # @return [String] Pluralized, humanized model name
       def label
-        model.model_name.human.pluralize
+        adapter.human_name.pluralize
       end
 
       # Returns the attribute used to display individual records.
@@ -652,57 +696,71 @@ module IronAdmin
       # @return [Symbol] The display attribute name
       def display_attribute
         ApplicationHelper::DISPLAY_METHODS.find do |method|
-          model.column_names.include?(method.to_s)
+          adapter.has_column?(method)
         end || :id
       end
 
-      # Checks if the model supports soft delete.
-      #
-      # @return [Boolean] True if model has a deleted_at column
-      def soft_delete?
-        model.column_names.include?(soft_delete_column)
+      SKIP_FILTER_COLUMNS = %w[id created_at updated_at].freeze
+      private_constant :SKIP_FILTER_COLUMNS
+
+      private
+
+      # Resolves the adapter class from a symbol or class.
+      # Symbols are resolved via the Adapters::Registry (lazy loading).
+      # Classes are used directly (for custom adapters).
+      def resolve_adapter_class
+        return adapter_class unless adapter_class.is_a?(Symbol)
+
+        Adapters::Registry.resolve(adapter_class)
       end
 
-      # Returns the column name used for soft delete tracking.
-      #
-      # @return [String] Column name (default: "deleted_at")
-      def soft_delete_column
-        "deleted_at"
+      # Resolves the resource class for an association configuration.
+      # Accepts Class, String, or falls back to ResourceRegistry lookup.
+      def resolve_association_resource(config, reflection)
+        resource = config[:resource]
+        return resource.constantize if resource.is_a?(String)
+        return resource if resource
+
+        ResourceRegistry.find(reflection.klass.model_name.plural)
       end
 
-      # Registers soft delete scopes and restore action if model supports it.
-      #
-      # Automatically called during resource initialization when
-      # a deleted_at column is detected.
-      #
-      # Registers:
-      # - :with_deleted scope - Show all records including soft-deleted
-      # - :only_deleted scope - Show only soft-deleted records
-      # - :restore action - Restore a soft-deleted record
-      #
-      # @return [void]
-      def register_soft_delete_features
-        return unless soft_delete?
-
-        # Capture the column name for use in lambdas
-        column = soft_delete_column
-        column_sym = column.to_sym
-
-        # Store soft delete scopes separately so they always appear after user-defined scopes
-        self._soft_delete_scopes = [
-          { name: :with_deleted, scope: -> { unscope(where: column_sym) }, default: false },
-          { name: :only_deleted, scope: -> { unscope(where: column_sym).where.not(column => nil) }, default: false },
-        ]
-
-        # Register restore action (only visible on soft-deleted records)
-        action :restore, icon: "arrow-path", condition: ->(record) { record.public_send(column).present? } do |record|
-          record.update(column => nil)
+      def enum_auto_filters
+        adapter.enums.map do |name, values|
+          {
+            name: name.to_sym,
+            type: :select,
+            options: values.keys,
+          }
         end
-      rescue ActiveRecord::NoDatabaseError, ActiveRecord::StatementInvalid
-        nil
       end
 
-      private
+      def infer_column_filters(enum_filters)
+        already_defined = (defined_filters + enum_filters).map { |f| f[:name].to_sym }
+
+        adapter.columns.filter_map do |col|
+          next if already_defined.include?(col.name.to_sym)
+          next if SKIP_FILTER_COLUMNS.include?(col.name)
+
+          infer_filter_from_column(col)
+        end
+      end
+
+      def infer_filter_from_column(col)
+        case col.type
+        when :string, :text
+          { name: col.name.to_sym, type: :string, label: col.name.humanize }
+        when :integer, :float, :decimal
+          return nil if col.name.end_with?("_id")
+
+          { name: col.name.to_sym, type: :number, label: col.name.humanize }
+        end
+      end
+
+      def coerce_action_fields(fields)
+        Array(fields).map do |f|
+          f.is_a?(ActionField) ? f : ActionField.new(**f)
+        end
+      end
 
       # @api private
       def infer_preload_associations

data/lib/iron_admin/resource_registry.rb

@@ -21,14 +21,68 @@ module IronAdmin
     class << self
       # Registers a resource class in the registry.
       #
-      # Called automatically when a Resource subclass is defined.
-      # Also triggers soft delete feature registration if applicable.
+      # Called automatically by `Resource.inherited`. The class is added to
+      # the registry hash **before** any model introspection so that even
+      # if soft-delete registration raises, the resource is still
+      # discoverable (and will be retried by {.finalize!}).
+      #
+      # The eager soft-delete call fires with whatever `adapter_class` is
+      # set at inheritance time, which for non-AR resources is the parent
+      # default (`:active_record`) — that's wrong but expected. The error
+      # is swallowed and {.finalize!} re-runs with the correct adapter
+      # after the class body has finished evaluating.
       #
       # @param resource_class [Class] The resource class to register
       # @return [Class] The registered resource class
       def register(resource_class)
-        resource_class.register_soft_delete_features
-        resources[resource_class.resource_name] = resource_class
+        # Stage the registry key first so the resource is discoverable
+        # even if `register_soft_delete_features` raises. We use a key
+        # derived from the class name (no adapter/model lookup) so HTTP
+        # resources without a Ruby model class — and any other case where
+        # `resource_name` would touch a not-yet-loaded adapter — still
+        # land in the registry.
+        resources[registry_key_for(resource_class)] = resource_class
+        begin
+          resource_class.register_soft_delete_features
+        rescue StandardError
+          # Swallow eager-registration failures silently — `finalize!`
+          # retries with the correct adapter once the class body has
+          # fully evaluated, and logs there.
+          nil
+        end
+        resource_class
+      end
+
+      # Runs every post-load registration step on every registered resource.
+      #
+      # Called by the engine's `to_prepare` block once all resource classes
+      # have been eager-loaded and their bodies have fully evaluated. By
+      # then `adapter_class`, `model_class_override`, etc. are set
+      # correctly, so model introspection through the adapter is safe.
+      #
+      # Soft-delete registration is idempotent; resources that succeeded
+      # eagerly during {.register} are skipped here. Failures are logged
+      # and swallowed per resource so a single broken resource (missing
+      # model class, unreachable DB, etc.) doesn't take down the boot.
+      #
+      # The cached `@adapter` instance is invalidated for every resource
+      # before re-running registration. The eager `Resource.adapter` call
+      # at inheritance time memoized an `Adapters::ActiveRecord.new(model)`
+      # — built with whatever `adapter_class` defaulted to before the
+      # class body's `self.adapter_class = :mongoid` (or `:http`) had
+      # taken effect. Without this invalidation, every subsequent
+      # `Resource.adapter` would keep returning that stale AR adapter
+      # and Mongoid/HTTP resources would 500 with `undefined method
+      # 'columns' for <MongoidModel>`.
+      #
+      # @return [void]
+      def finalize!
+        all.each do |resource_class|
+          resource_class.instance_variable_set(:@adapter, nil)
+          resource_class.register_soft_delete_features
+        rescue StandardError => e
+          warn_finalize_failure(resource_class, e)
+        end
       end
 
       # Returns all registered resource classes.
@@ -89,6 +143,25 @@ module IronAdmin
       def resources
         @resources ||= {}
       end
+
+      # Builds the registry key without touching the adapter or model.
+      # Falls back from `resource_class.resource_name` (which delegates
+      # to the adapter and may raise on HTTP/Mongoid resources before
+      # `to_prepare` finalizes the lifecycle) to a name derived purely
+      # from the class identifier.
+      def registry_key_for(resource_class)
+        resource_class.resource_name
+      rescue StandardError
+        resource_class.name.demodulize.sub(/Resource\z/, "").underscore.pluralize
+      end
+
+      def warn_finalize_failure(resource_class, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        Rails.logger.warn(
+          "[IronAdmin] Could not finalize #{resource_class.name}: #{error.class} (#{error.message})"
+        )
+      end
     end
   end
 end

data/lib/iron_admin/tool.rb

@@ -1,12 +1,40 @@
 # frozen_string_literal: true
 
 module IronAdmin
+  # Base class for admin tools (custom pages in the admin panel).
+  #
+  # Tools are standalone pages that don't map to a database model.
+  # External gems can subclass Tool to add custom admin functionality.
+  #
+  # @example Simple tool with declarative actions
+  #   class CacheManagerTool < IronAdmin::Tool
+  #     menu icon: "server", label: "Cache Manager", group: "System"
+  #
+  #     tool_action :clear_all, icon: "trash", confirm: true
+  #     tool_action :flush_key,
+  #       form_fields: [{ name: :cache_key, type: :text, required: true }]
+  #
+  #     def clear_all(ctx)
+  #       Rails.cache.clear
+  #       ctx.flash[:notice] = "Cache cleared!"
+  #     end
+  #
+  #     def flush_key(ctx)
+  #       key = ctx.action_params(:cache_key)[:cache_key]
+  #       Rails.cache.delete(key)
+  #     end
+  #   end
   class Tool
     class_attribute :menu_options, default: {}
+    class_attribute :defined_tool_actions, default: []
+
+    # @return [ToolContext, nil] Request context, set by ToolsController before action execution
+    attr_accessor :context
 
     class << self
       def inherited(subclass)
         super
+        subclass.defined_tool_actions = defined_tool_actions.dup
         return if subclass.name.nil?
 
         begin
@@ -16,6 +44,28 @@ module IronAdmin
         end
       end
 
+      # Declares a tool action with metadata.
+      #
+      # @param name [Symbol] Method name to call when action is executed
+      # @param options [Hash] Action options passed to ToolAction.new
+      # @option options [String] :label Display label
+      # @option options [String] :icon Heroicon name
+      # @option options [Boolean] :confirm Show confirmation dialog
+      # @option options [String] :confirm_message Custom confirmation text
+      # @option options [Array<Hash, ActionField>] :form_fields Fields to collect before execution
+      # @option options [Proc] :condition Proc receiving user, returns boolean
+      def tool_action(name, **)
+        self.defined_tool_actions = defined_tool_actions + [ToolAction.new(name: name, **)]
+      end
+
+      # Finds a declared tool action by name.
+      #
+      # @param name [Symbol, String] Action name
+      # @return [ToolAction, nil]
+      def find_tool_action(name)
+        defined_tool_actions.find { |a| a.name == name.to_sym }
+      end
+
       def menu(**options)
         self.menu_options = options
       end

data/lib/iron_admin/tool_action.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  # Value object representing a declared action on a Tool.
+  #
+  # Stores action metadata: display label, icon, confirmation settings,
+  # form fields to collect before execution, and authorization condition.
+  #
+  # @example
+  #   ToolAction.new(
+  #     name: :run_task,
+  #     label: "Run Task",
+  #     icon: "play",
+  #     confirm: true,
+  #     form_fields: [{ name: :task_name, type: :select, options: %w[db:migrate db:seed] }],
+  #     condition: ->(user) { user.admin? }
+  #   )
+  class ToolAction
+    # @return [Symbol] Action method name
+    attr_reader :name
+
+    # @return [String] Display label
+    attr_reader :label
+
+    # @return [String, nil] Heroicon name
+    attr_reader :icon
+
+    # @return [Boolean] Whether to show confirmation dialog
+    attr_reader :confirm
+
+    # @return [String, nil] Custom confirmation message
+    attr_reader :confirm_message
+
+    # @return [Array<ActionField>] Form fields to collect before execution
+    attr_reader :form_fields
+
+    # @return [Proc, nil] Condition proc that receives current_user, returns boolean
+    attr_reader :condition
+
+    def initialize(name:, label: nil, icon: nil, confirm: false, confirm_message: nil, form_fields: [], condition: nil)
+      @name = name.to_sym
+      @label = label || name.to_s.humanize
+      @icon = icon
+      @confirm = confirm
+      @confirm_message = confirm_message
+      @form_fields = coerce_form_fields(form_fields)
+      @condition = condition
+    end
+
+    # @return [Boolean] Whether this action has form fields to collect
+    def has_form? # rubocop:disable Naming/PredicatePrefix
+      form_fields.any?
+    end
+
+    # Checks if the action is allowed for the given user.
+    #
+    # @param user [Object, nil] Current user
+    # @return [Boolean]
+    def allowed?(user)
+      return true if condition.nil?
+
+      condition.call(user)
+    end
+
+    private
+
+    def coerce_form_fields(fields)
+      Array(fields).map do |f|
+        f.is_a?(ActionField) ? f : ActionField.new(**f)
+      end
+    end
+  end
+end

data/lib/iron_admin/tool_context.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  # Lightweight request context injected into Tool instances before action execution.
+  #
+  # Provides tools with access to request params, the current user, and flash messages
+  # without coupling them to the controller.
+  #
+  # @example Accessing context in a tool action
+  #   class ReportTool < IronAdmin::Tool
+  #     tool_action :generate
+  #
+  #     def generate(ctx)
+  #       user = ctx.current_user
+  #       format = ctx.action_params(:format)[:format]
+  #       ctx.flash[:notice] = "Report generated for #{user.name}"
+  #     end
+  #   end
+  class ToolContext
+    # @return [ActionController::Parameters] Raw request params
+    attr_reader :params
+
+    # @return [Object, nil] Current authenticated user
+    attr_reader :current_user
+
+    # @return [ActionDispatch::Flash::FlashHash] Flash messages
+    attr_reader :flash
+
+    # @param params [ActionController::Parameters]
+    # @param current_user [Object, nil]
+    # @param flash [ActionDispatch::Flash::FlashHash]
+    def initialize(params:, current_user:, flash:)
+      @params = params
+      @current_user = current_user
+      @flash = flash
+    end
+
+    # Extracts and permits only the specified keys from tool_action params.
+    #
+    # @param keys [Array<Symbol>] Keys to permit
+    # @return [Hash] Permitted params as a symbolized hash
+    def action_params(*keys)
+      raw = params.fetch(:tool_action, {})
+      return {} unless raw.respond_to?(:permit)
+
+      raw.permit(*keys).to_h.symbolize_keys
+    end
+  end
+end

data/lib/iron_admin/version.rb

@@ -3,5 +3,5 @@
 module IronAdmin
   # The current version of the IronAdmin gem.
   # @return [String]
-  VERSION = "0.4.1"
+  VERSION = "0.6.0"
 end