iron_admin 0.5.0 → 0.6.0

data/docs/guides/extending.md

@@ -12,6 +12,69 @@ IronAdmin is designed to be extended at every level.
 6. **Theme system** - 40+ CSS class properties
 7. **Route mounting** - Mount at any path
 
+## MongoDB / Mongoid Support
+
+IronAdmin supports MongoDB via the built-in Mongoid adapter. Add `mongoid` to your Gemfile and configure resources:
+
+```ruby
+# Gemfile
+gem "mongoid"
+
+# app/iron_admin/resources/article_resource.rb
+module IronAdmin
+  module Resources
+    class ArticleResource < IronAdmin::Resource
+      self.adapter_class = :mongoid
+    end
+  end
+end
+```
+
+The Mongoid adapter:
+- Maps Mongoid field types to IronAdmin field types automatically
+- Supports `embeds_many`/`embeds_one` associations (mapped to `:has_many`/`:has_one`)
+- Uses `$regex` for case-insensitive search
+- Provides a `MongoidQueryBuilder` for operator-based string/number filters
+- Falls back gracefully for MongoDB standalone (transactions require replica set)
+
+You can mix adapters in the same app — some resources using ActiveRecord, others using Mongoid.
+
+## HTTP REST API Support
+
+IronAdmin can manage resources from external REST APIs. Add `faraday` to your Gemfile:
+
+```ruby
+# Gemfile
+gem "faraday"
+
+# config/initializers/iron_admin.rb
+IronAdmin.configure do |config|
+  config.http_base_url = "https://api.example.com/v1"
+  config.http_headers = { "Authorization" => "Bearer #{ENV['API_TOKEN']}" }
+end
+
+# app/iron_admin/resources/product_resource.rb
+module IronAdmin
+  module Resources
+    class ProductResource < IronAdmin::Resource
+      self.adapter_class = :http
+
+      # Fields auto-discovered from API response. Just customize:
+      field :status, type: :badge
+      searchable :name
+    end
+  end
+end
+```
+
+The HTTP adapter:
+- Auto-discovers fields from the first API response (convention-over-configuration)
+- Infers resource path from name (`ProductResource` → `GET /products`)
+- Full CRUD via standard REST verbs
+- Lazy query execution (no HTTP requests until records are accessed)
+- Populates `record.errors` from API 422 responses for form validation
+- **Does not require a Ruby model class.** When `adapter_class = :http`, `Resource.model` returns `IronAdmin::Adapters::Http::ModelProxy` — a thin wrapper exposing `model_name.plural` / `model_name.human` for routing and labels, and an empty `column_names` (HTTP resources have no static schema). Fields are discovered from the API response at request time.
+
 ## Custom Resources with Business Logic
 
 ```ruby
@@ -154,8 +217,12 @@ Create a tool class that inherits from `IronAdmin::Tool`:
 
 ```ruby
 # app/iron_admin/tools/report_tool.rb
-class ReportTool < IronAdmin::Tool
-  menu label: "Reports", icon: "chart-bar", priority: 1, group: "Analytics"
+module IronAdmin
+  module Tools
+    class ReportTool < IronAdmin::Tool
+      menu label: "Reports", icon: "chart-bar", priority: 1, group: "Analytics"
+    end
+  end
 end
 ```
 
@@ -169,7 +236,7 @@ Create a view template for your tool at:
 app/views/iron_admin/tools/<tool_name>/show.html.erb
 ```
 
-For example, `ReportTool` (which has `tool_name` of `"report"`) would use:
+For example, `IronAdmin::Tools::ReportTool` (which has `tool_name` of `"report"`) would use:
 
 ```
 app/views/iron_admin/tools/report/show.html.erb
@@ -184,6 +251,54 @@ Tools are automatically routed at `/admin/tools/:tool_name`:
 | `GET /admin/tools/:tool_name` | `tools#show` | Render the tool's show view |
 | `POST /admin/tools/:tool_name/:action_name` | `tools#execute` | Execute a tool action |
 
+### Declarative Tool Actions
+
+Use `tool_action` to declare actions with metadata, form fields, and authorization:
+
+```ruby
+# app/iron_admin/tools/cache_manager_tool.rb
+module IronAdmin
+  module Tools
+    class CacheManagerTool < IronAdmin::Tool
+      menu label: "Cache Manager", icon: "server", group: "System"
+
+      tool_action :flush_all,
+        label: "Flush All Caches",
+        icon: "trash",
+        confirm: true,
+        condition: ->(user) { user&.admin? }
+
+      tool_action :flush_key,
+        label: "Flush Specific Key",
+        form_fields: [
+          { name: :cache_key, type: :text, required: true, placeholder: "e.g. users/123" }
+        ]
+
+      def flush_all(ctx)
+        Rails.cache.clear
+        ctx.flash[:notice] = "All caches flushed"
+      end
+
+      def flush_key(ctx)
+        key = ctx.action_params(:cache_key)[:cache_key]
+        Rails.cache.delete(key)
+        ctx.flash[:notice] = "Key '#{key}' flushed"
+      end
+    end
+  end
+end
+```
+
+**ToolContext** is injected into 1-arg methods and provides:
+- `ctx.params` — raw request params
+- `ctx.current_user` — the current admin user
+- `ctx.flash` — flash messages
+- `ctx.action_params(:key1, :key2)` — safe param extraction (strong params)
+
+**Authorization:** The `condition:` proc receives the current user. If it returns false, the action returns 403 and is hidden from the UI.
+
+**Form fields:** Actions with `form_fields:` render a form page before execution. Supported types: `:text`, `:textarea`, `:number`, `:boolean`, `:date`, `:datetime`, `:select`.
+
 ### Menu Options
 
 | Option | Type | Description |
@@ -193,6 +308,14 @@ Tools are automatically routed at `/admin/tools/:tool_name`:
 | `priority` | Integer | Sort order (lower = higher in sidebar) |
 | `group` | String | Sidebar group heading (defaults to "Tools") |
 
+### Tool Routes
+
+| Route | Controller Action | Description |
+|-------|-------------------|-------------|
+| `GET /admin/tools/:tool_name` | `tools#show` | Render the tool's show view |
+| `GET /admin/tools/:tool_name/:action_name/form` | `tools#action_form` | Render action form |
+| `POST /admin/tools/:tool_name/:action_name` | `tools#execute` | Execute a tool action |
+
 ### ToolRegistry API
 
 | Method | Description |
@@ -283,6 +406,12 @@ IronAdmin.configure do |config|
 end
 ```
 
+## Custom Adapters
+
+IronAdmin uses an adapter pattern to decouple from any specific ORM. It ships with `ActiveRecord` and `Mongoid` adapters, but you can create adapters for any data source (Sequel, HTTP APIs, DynamoDB, etc.).
+
+See the [Building a Custom Adapter](custom-adapters.md) guide for the complete reference, including all 35 methods, duck type contracts, QueryBuilder integration, and testing patterns.
+
 ## Testing Resources
 
 ```ruby

data/docs/guides/fields.md

@@ -1,6 +1,6 @@
 # Fields
 
-IronAdmin automatically infers field types from your ActiveRecord model's database schema.
+IronAdmin automatically infers field types from your model's schema (ActiveRecord columns or Mongoid fields).
 
 ## Automatic Inference
 

data/docs/guides/resources.md

@@ -1,6 +1,6 @@
 # Resources
 
-Resources are the core building block of IronAdmin. Each resource maps to an ActiveRecord model and defines how it appears in the admin panel.
+Resources are the core building block of IronAdmin. Each resource maps to a model (ActiveRecord or Mongoid) and defines how it appears in the admin panel.
 
 ## Generating a Resource
 
@@ -112,6 +112,21 @@ remove_filter :some_column
 | `:select` | Dropdown with choices |
 | `:date_range` | Date range picker |
 | `:boolean` | True/false toggle |
+| `:string` | Text input with operator dropdown (contains, equals, starts_with, ends_with) |
+| `:number` | Number input with operator dropdown (equals, greater_than, less_than, between) |
+
+### String and Number Filters
+
+String and number filters provide an operator dropdown alongside the input:
+
+```ruby
+class ProductResource < IronAdmin::Resource
+  filter :name, type: :string       # contains, equals, starts_with, ends_with
+  filter :price, type: :number      # equals, greater_than, less_than, between
+end
+```
+
+**Auto-inference:** String and text columns automatically infer as `:string` filters. Integer, float, and decimal columns automatically infer as `:number` filters. You only need explicit declarations to override defaults or add filters for columns that aren't auto-detected.
 
 ### Auto-Generated Enum Filters
 
@@ -186,6 +201,36 @@ action :process do |record|
 end
 ```
 
+### Action Forms
+
+Actions can collect user input before executing by specifying `form_fields:`. The form is displayed in a modal when the action is triggered.
+
+```ruby
+class OrderResource < IronAdmin::Resource
+  action :reject,
+    form_fields: [
+      action_field(:reason, type: :textarea, required: true),
+      action_field(:notify_customer, type: :boolean, default: true)
+    ] do |record, params|
+      record.reject!(reason: params[:reason])
+      Mailer.rejection(record).deliver_later if params[:notify_customer]
+    end
+end
+```
+
+**ActionField types:** `text`, `textarea`, `number`, `boolean`, `date`, `datetime`, `select`.
+
+ActionField options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | Symbol | Input type (see list above) |
+| `required` | Boolean | Whether the field must be filled |
+| `default` | Object | Default value for the input |
+| `choices` | Array | Options for `:select` type |
+
+Action forms work with both record actions and bulk actions.
+
 ### Bulk Actions
 
 ```ruby
@@ -272,6 +317,37 @@ class OrderResource < IronAdmin::Resource
 end
 ```
 
+## Nested Forms
+
+For `has_many` and `has_one` associations, you can enable inline nested editing directly on the parent form. The model must declare `accepts_nested_attributes_for` for the association.
+
+```ruby
+class OrderResource < IronAdmin::Resource
+  # has_many with nested editing
+  has_many :line_items, nested: true, allow_destroy: true
+
+  # Explicit field selection
+  has_many :addresses, nested: true, fields: [:street, :city, :zip]
+
+  # With drag-and-drop ordering (via Stimulus)
+  has_many :sections, nested: true, position_field: :position
+
+  # has_one nested
+  has_one :profile, nested: true
+end
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `nested` | `false` | Enable inline nested form for the association |
+| `allow_destroy` | `true` | Allow removing child records from the form |
+| `fields` | auto-inferred | Explicit list of child fields to display (excludes `id`, timestamps, and FK by default) |
+| `position_field` | `nil` | Column name for drag-and-drop reordering |
+
+Nested forms use the existing `create` and `update` endpoints -- no additional routes are required. Child attributes are submitted as standard Rails nested attributes (`*_attributes` params).
+
 ## Menu Configuration
 
 ```ruby
@@ -300,7 +376,7 @@ Exports respect:
 class UserResource < IronAdmin::Resource
   policy do
     allow :read, :update
-    deny :delete, if: ->(record) { record.admin? }
+    deny :destroy, if: ->(user) { !user.superadmin? }
   end
 end
 ```

data/docs/guides/troubleshooting.md

@@ -96,6 +96,35 @@ closed. This is the recommended workaround until the issue is resolved upstream.
 1. Ensure resource file exists in `app/iron_admin/resources/`
 2. Check resource inherits from `IronAdmin::Resource`
 3. Verify filename matches class name (`user_resource.rb` → `UserResource`)
+4. For non-AR adapters (`:mongoid`, `:http`, custom): registration runs in
+   two phases — `Resource.inherited` adds the class to the registry, and
+   the engine's `to_prepare` block calls `ResourceRegistry.finalize!`
+   after every class body has fully evaluated. If you call
+   `IronAdmin::ResourceRegistry.register` manually outside the engine's
+   boot path (e.g. in custom initializer), call
+   `IronAdmin::ResourceRegistry.finalize!` afterwards so soft-delete
+   features pick up the right adapter.
+
+### Resources silently missing on Mongoid / HTTP / custom adapters
+
+**Cause:** Eager registration tried to introspect the model before
+`self.adapter_class = :mongoid` (or similar) had taken effect. The eager
+failure is **silent by design** (no log line) — `finalize!` retries with
+the correct adapter once the class body has fully evaluated. Logs only
+appear if the deferred retry *also* fails.
+
+**Solutions:**
+1. Look for `[IronAdmin] Could not finalize <Resource>: <Error>` in
+   `Rails.logger`. If you see one, the deferred retry failed too —
+   common causes: model class doesn't exist (HTTP adapter), DB
+   unreachable (transient outage at boot), or schema introspection bug
+   in the adapter.
+2. Confirm the registry has the resource:
+   `bin/rails runner 'puts IronAdmin::ResourceRegistry.find("things")'`
+3. If `find` returns `nil` and there's no `Could not finalize` log,
+   `finalize!` may not have run yet (e.g. the engine's `to_prepare`
+   wasn't triggered in your boot path). Run
+   `IronAdmin::ResourceRegistry.finalize!` manually and re-check.
 
 ### Custom actions not appearing
 

data/docs/reference/routes.md

@@ -16,9 +16,19 @@ Mount: `mount IronAdmin::Engine => "/admin"`
 | POST | `/admin/:resource` | `resources#create` | Create |
 | PATCH | `/admin/:resource/:id` | `resources#update` | Update |
 | DELETE | `/admin/:resource/:id` | `resources#destroy` | Delete |
+| GET | `/admin/:resource/:id/actions/:name/form` | `resources#action_form` | Action form |
 | POST | `/admin/:resource/:id/actions/:name` | `resources#execute_action` | Custom action |
+| GET | `/admin/:resource/bulk_actions/:name/form` | `resources#bulk_action_form` | Bulk action form |
 | POST | `/admin/:resource/bulk_actions/:name` | `resources#execute_bulk_action` | Bulk action |
 
+### Tool Routes
+
+| Method | Path | Action | Description |
+|--------|------|--------|-------------|
+| GET | `/admin/tools/:tool_name` | `tools#show` | Tool page |
+| GET | `/admin/tools/:tool_name/:action_name/form` | `tools#action_form` | Tool action form |
+| POST | `/admin/tools/:tool_name/:action_name` | `tools#execute` | Execute tool action |
+
 ## Query Parameters (Index)
 
 | Param | Example |

data/lib/generators/iron_admin/install/install_generator.rb

@@ -44,20 +44,44 @@ module IronAdmin
         route 'mount IronAdmin::Engine => "/admin"'
       end
 
+      # Candidate Tailwind entry points, in priority order. Covers
+      # tailwindcss-rails 4.x layout (`app/assets/tailwind/application.css`)
+      # and the tailwindcss-rails 3.x / cssbundling-rails layout
+      # (`app/assets/stylesheets/application.tailwind.css`).
+      TAILWIND_CSS_CANDIDATES = %w[
+        app/assets/tailwind/application.css
+        app/assets/stylesheets/application.tailwind.css
+      ].freeze
+
       # Adds the IronAdmin CSS import to the Tailwind application stylesheet.
       #
       # This import is required so the Tailwind compiler scans the engine's
       # views and components for CSS utility classes. Without it, the admin
       # panel renders unstyled.
       #
+      # If no known Tailwind entry point is detected (e.g. the host added
+      # `gem "iron_admin"` after `rails new --skip-bundle`, before the
+      # tailwindcss installer ran), the generator emits a yellow `skip`
+      # status line with the exact `@import` directive the user needs to
+      # add manually — instead of returning silently and leaving the admin
+      # panel unstyled with no breadcrumb to the cause.
+      #
       # @return [void]
       def add_tailwind_import
-        css_path = "app/assets/tailwind/application.css"
-        return unless File.exist?(File.join(destination_root, css_path))
-
         import_line = '@import "../builds/tailwind/iron_admin";'
-        content = File.read(File.join(destination_root, css_path))
 
+        css_path = TAILWIND_CSS_CANDIDATES.find { |p| File.exist?(File.join(destination_root, p)) }
+
+        unless css_path
+          say_status :skip,
+                     "no Tailwind entry point found; add #{import_line} to your Tailwind " \
+                     "application file once it's created (typically " \
+                     "#{TAILWIND_CSS_CANDIDATES.first})",
+                     :yellow
+          return
+        end
+
+        content = File.read(File.join(destination_root, css_path))
         return if content.include?(import_line)
 
         append_to_file css_path, "#{import_line}\n"

data/lib/generators/iron_admin/install_audit/install_audit_generator.rb

@@ -20,22 +20,38 @@ module IronAdmin
     # @see IronAdmin::AuditLog
     # @see IronAdmin::Configuration#audit_storage
     class InstallAuditGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
-
       source_root File.expand_path("templates", __dir__)
 
-      # Creates the audit entries migration.
+      # Writes the audit entries migration into `db/migrate/`.
+      #
+      # We deliberately avoid `Rails::Generators::Migration#migration_template`
+      # here: that helper goes through `ActiveRecord::Migration.current_version`
+      # which opens a DB connection to read the schema cache. On a clean
+      # machine (DB doesn't exist yet) or during a deploy where the DB
+      # is briefly unreachable, that crashes the generator with
+      # `ActiveRecord::ConnectionNotEstablished` and the migration file
+      # never gets written. Using plain `template` plus a timestamp-based
+      # filename keeps the generator DB-free, so `bin/rails db:create
+      # db:migrate` (the natural bootstrap order) Just Works.
+      #
       # @return [void]
       def create_migration
-        migration_template "create_iron_admin_audit_entries.rb.tt",
-                           "db/migrate/create_iron_admin_audit_entries.rb"
+        timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        target = "db/migrate/#{timestamp}_create_iron_admin_audit_entries.rb"
+        if existing_audit_migration?
+          say_status :skip, "create_iron_admin_audit_entries migration already exists", :yellow
+          return
+        end
+        template "create_iron_admin_audit_entries.rb.tt", target
       end
 
-      # @api private
-      # Generates the next migration number based on current timestamp.
-      # @return [String] Migration timestamp
-      def self.next_migration_number(_dirname)
-        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      private
+
+      # @return [Boolean] True if a migration whose name ends with
+      #   `_create_iron_admin_audit_entries.rb` is already present in
+      #   `db/migrate/`. Avoids creating duplicate migrations on rerun.
+      def existing_audit_migration?
+        Dir.glob(File.join(destination_root, "db/migrate", "*_create_iron_admin_audit_entries.rb")).any?
       end
     end
   end

data/lib/iron_admin/action_field.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  # Value object representing a single field in an action form.
+  #
+  # ActionFields define what inputs are shown to the user when an action
+  # requires parameters before execution (e.g., a reason, a date, a choice).
+  #
+  # @example Creating an action field
+  #   ActionField.new(name: :reason, type: :textarea, required: true)
+  #
+  # @example Creating a select field with options
+  #   ActionField.new(name: :priority, type: :select, options: %w[low medium high])
+  class ActionField
+    # Supported field types for action forms.
+    TYPES = %i[text textarea number boolean date datetime select].freeze
+
+    # @return [Symbol] The field name (used as the param key)
+    attr_reader :name
+
+    # @return [Symbol] The field type
+    attr_reader :type
+
+    # @return [String] Human-readable label for the field
+    attr_reader :label
+
+    # @return [Boolean] Whether the field is required
+    attr_reader :required
+
+    # @return [Object, nil] Default value for the field
+    attr_reader :default
+
+    # @return [String, nil] Placeholder text for the input
+    attr_reader :placeholder
+
+    # @return [Array, nil] Options for select fields
+    attr_reader :options
+
+    # @param name [Symbol, String] The field name (converted to Symbol)
+    # @param type [Symbol, String] The field type (defaults to :text)
+    # @param label [String, nil] Custom label (inferred from name if nil)
+    # @param required [Boolean] Whether the field is required (default: false)
+    # @param default [Object, nil] Default value for the field
+    # @param placeholder [String, nil] Placeholder text
+    # @param options [Array, nil] Options for select fields
+    def initialize(name:, type: :text, label: nil, required: false, default: nil, placeholder: nil, options: nil)
+      @name = name.to_sym
+      @type = TYPES.include?(type.to_sym) ? type.to_sym : :text
+      @label = label || name.to_s.humanize
+      @required = required
+      @default = default
+      @placeholder = placeholder
+      @options = options
+    end
+  end
+end