iron_admin 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a7e6f008423227296c7d793dc516a5e535249bedececc1c41af83dd91a019d4
-  data.tar.gz: 1eb8f4c673a35d21fd1f04bc38fa72d55fba0e984cccc965156bc273f9696ab3
+  metadata.gz: cd7c68ca4e035fc4fe1b47d4c3415e76dcbb9ba77a53e9a574abe55a7e3bd6c9
+  data.tar.gz: 95ef292dd61db7778af10963a749cc63a9f67e9ecda2a8f115207522ffb28caf
 SHA512:
-  metadata.gz: 7259b141211a0575f49d8df3dc3f22fc3d421b0ef60a31770b26aff5da46da70d566a8e6c4255723f836ce7995c39ea4b5764a036dc96157b42004897d52aade
-  data.tar.gz: fb326e0e209721a1341c8b0740325f2129a5d8e66de8ba2697f3e6325a271227961128c786c25574c88006333c4887c3d805055584284c7589ac925290c45ef3
+  metadata.gz: 056e8a6cf97e585a4d979e303aa2a9ca10618b50e6fb75a5f61d5c52070adb7d8d4ae65498eefad9346700eb8ad629a11203a8fc940bd0f96cf44065e2b02b3e
+  data.tar.gz: 419a9faf097e0a4f0beab00624eb7e79876cb1b6fbce0d61703dd13f3d879b102586d1271bb58073e7da1dd7cb0709776b625f9cfefaaac41881ecb9be79c259

data/README.md

@@ -20,6 +20,7 @@ Convention-over-configuration admin panel engine for Ruby on Rails. Build beauti
 
 - Ruby >= 3.2
 - Rails >= 7.1
+- [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) >= 4.0
 
 ## Installation
 
@@ -27,6 +28,7 @@ Add to your Gemfile:
 
 ```ruby
 gem "iron_admin"
+gem "tailwindcss-rails"
 ```
 
 Then run:
@@ -36,14 +38,40 @@ bundle install
 rails generate iron_admin:install
 ```
 
-Mount the engine in your `config/routes.rb`:
+The install generator will:
+- Create `app/iron_admin/resources/` and `app/iron_admin/dashboards/` directories
+- Add a configuration initializer at `config/initializers/iron_admin.rb`
+- Create a sample dashboard
+- Mount the engine at `/admin` in your routes
+- Add the IronAdmin Tailwind CSS import to your `app/assets/tailwind/application.css`
 
-```ruby
-Rails.application.routes.draw do
-  mount IronAdmin::Engine, at: "/admin"
-end
+### Tailwind CSS Setup
+
+IronAdmin uses Tailwind CSS v4 for all styling. The `tailwindcss-rails` gem handles
+compilation. After running the install generator, your `app/assets/tailwind/application.css`
+should include:
+
+```css
+@import "tailwindcss";
+@import "../builds/tailwind/iron_admin";
+```
+
+The second line imports IronAdmin's `@source` directives so the Tailwind compiler
+scans the engine's views and components for CSS classes. Without it, the admin panel
+will render unstyled.
+
+If you're setting up manually (without the generator), run:
+
+```bash
+rails tailwindcss:build
 ```
 
+Then verify that `app/assets/builds/tailwind/iron_admin.css` was created. If not,
+check that `tailwindcss-rails` >= 4.0 is installed and that the engine gem is properly
+loaded.
+
+For development, use `bin/dev` or `rails tailwindcss:watch` to recompile CSS on changes.
+
 ## Quick Start
 
 ### 1. Configure Authentication
@@ -75,26 +103,30 @@ rails generate iron_admin:resource Order
 ### 3. Customize Resources
 
 ```ruby
-# app/iron_admin/user_resource.rb
-class UserResource < IronAdmin::Resource
-  field :role, type: :badge, colors: { admin: :purple, user: :blue }
-  field :email, type: :text
+# app/iron_admin/resources/user_resource.rb
+module IronAdmin
+  module Resources
+    class UserResource < IronAdmin::Resource
+      field :role, type: :badge, colors: { admin: :purple, user: :blue }
+      field :email, type: :text
 
-  searchable :name, :email
+      searchable :name, :email
 
-  filter :role, type: :select, choices: User.roles.keys
-  filter :created_at, type: :date_range
+      filter :role, type: :select, choices: User.roles.keys
+      filter :created_at, type: :date_range
 
-  scope :admins, -> { where(role: :admin) }
-  scope :recent, -> { where("created_at > ?", 7.days.ago) }
+      scope :admins, -> { where(role: :admin) }
+      scope :recent, -> { where("created_at > ?", 7.days.ago) }
 
-  index_fields :id, :name, :email, :role, :created_at
-  form_fields :name, :email, :role
+      index_fields :id, :name, :email, :role, :created_at
+      form_fields :name, :email, :role
 
-  menu priority: 1, icon: "users", group: "People"
+      menu priority: 1, icon: "users", group: "People"
 
-  action :lock, icon: "lock-closed", confirm: true do |record|
-    record.update!(locked_at: Time.current)
+      action :lock, icon: "lock-closed", confirm: true do |record|
+        record.update!(locked_at: Time.current)
+      end
+    end
   end
 end
 ```
@@ -102,18 +134,22 @@ end
 ### 4. Create a Dashboard
 
 ```ruby
-# app/iron_admin/admin_dashboard.rb
-class AdminDashboard < IronAdmin::Dashboard
-  metric :total_users, format: :number do
-    User.count
+# app/iron_admin/dashboards/admin_dashboard.rb
+module IronAdmin
+  module Dashboards
+    class AdminDashboard < IronAdmin::Dashboard
+      metric :total_users, format: :number do
+        User.count
+      end
+
+      metric :monthly_revenue, format: :currency do
+        Payment.where("created_at > ?", 30.days.ago).sum(:amount)
+      end
+
+      recent :users, limit: 5, scope: -> { order(created_at: :desc) }
+      recent :payments, limit: 5
+    end
   end
-
-  metric :monthly_revenue, format: :currency do
-    Payment.where("created_at > ?", 30.days.ago).sum(:amount)
-  end
-
-  recent :users, limit: 5, scope: -> { order(created_at: :desc) }
-  recent :payments, limit: 5
 end
 ```
 

data/app/assets/config/iron_admin_manifest.js

@@ -0,0 +1,12 @@
+// Sprockets manifest for IronAdmin engine assets.
+// Engine initializer adds this manifest to the host's precompile list,
+// recursively pulling these assets into Sprockets' precompile set.
+
+// Stimulus / importmap entry point + controllers.
+//= link_tree ../../javascript/iron_admin .js
+
+// Chart.js (vendored) — loaded by the dashboard layout via
+// `javascript_include_tag "chart.min"`. Without this link, hosts on
+// sprockets-rails 500 on `/admin` with
+// `Asset 'chart.min.js' was not declared to be precompiled`.
+//= link chart.min.js

data/app/components/iron_admin/dashboards/metric_card_component.html.haml

@@ -1,3 +1,8 @@
-.bg-white.rounded-lg.shadow.p-6
-  %p.text-sm.font-medium.text-gray-500= label
-  %p.mt-2.text-3xl.font-bold.text-gray-900= formatted_value
+.bg-white.rounded-lg.shadow.p-6{ id: (live_target_id if live?) }
+  .flex.items-center.justify-between
+    %div
+      %p.text-sm.font-medium.text-gray-500= label
+      %p.mt-2.text-3xl.font-bold.text-gray-900= formatted_value
+    - if icon
+      .flex-shrink-0.p-3.bg-indigo-50.rounded-lg
+        = heroicon icon, variant: :outline, options: { class: "h-6 w-6 text-indigo-600" }

data/app/components/iron_admin/dashboards/metric_card_component.rb

@@ -7,10 +7,14 @@ module IronAdmin
       # @param name [String, Symbol] Metric name
       # @param value [Numeric] Metric value
       # @param format [Symbol] Format (:number, :currency, :percentage)
-      def initialize(name:, value:, format: :number)
+      # @param icon [String, nil] Optional Heroicon name (e.g., "users", "currency-dollar")
+      # @param live [Boolean] Whether to render a stable Turbo Stream target id
+      def initialize(name:, value:, format: :number, icon: nil, live: false)
         @name = name
         @value = value
         @format = format
+        @icon = icon
+        @live = live
       end
 
       # @api private
@@ -28,6 +32,22 @@ module IronAdmin
       def label
         @name.to_s.humanize
       end
+
+      # @api private
+      # @return [Boolean] True when the metric should expose a live target
+      def live?
+        @live
+      end
+
+      # @api private
+      # @return [String] Stable Turbo Stream target id
+      def live_target_id
+        "metric_#{@name.to_s.parameterize(separator: "_")}"
+      end
+
+      # @api private
+      # @return [String, nil] Heroicon name
+      attr_reader :icon
     end
   end
 end

data/app/components/iron_admin/form/belongs_to_component.rb

@@ -15,6 +15,12 @@ module IronAdmin
       # @return [Integer]
       DEFAULT_OPTIONS_LIMIT = 100
 
+      # Methods tried (in order) when no explicit `display_method:` is
+      # passed, or when the explicit method returns a blank value.
+      # Single source of truth lives on `IronAdmin::ApplicationHelper`
+      # so forms and show/index pages can never silently drift apart.
+      DISPLAY_METHOD_FALLBACKS = IronAdmin::ApplicationHelper::DISPLAY_METHODS
+
       # @return [String] Select name attribute
       attr_reader :name
 
@@ -45,13 +51,17 @@ module IronAdmin
       # @param name [String] Select name
       # @param association_class [Class] Associated model class
       # @param selected [Integer, nil] Selected ID
-      # @param display_method [Symbol] Display method (default: :name)
+      # @param display_method [Symbol, Proc, nil] Custom display method.
+      #   Pass `nil` (the default) to let the component auto-detect a
+      #   sensible label from `IronAdmin::ApplicationHelper::DISPLAY_METHODS`
+      #   (`:name`, `:title`, `:email`, `:label`, `:slug`), falling back
+      #   to `"<Model> #<id>"` if none of those exist.
       # @param include_blank [Boolean] Include blank option
       # @param disabled [Boolean] Disabled state
       # @param has_error [Boolean] Error state
       # @param options_limit [Integer] Max options
       # @param options_scope [Proc, nil] Custom scope
-      def initialize(name:, association_class:, selected: nil, display_method: :name,
+      def initialize(name:, association_class:, selected: nil, display_method: nil,
                      include_blank: true, disabled: false, has_error: false,
                      options_limit: DEFAULT_OPTIONS_LIMIT, options_scope: nil)
         @name = name
@@ -74,16 +84,43 @@ module IronAdmin
       # @api private
       # @return [Array<Array(String, Integer)>] Options array for select tag
       def options
-        scope = options_scope ? association_class.instance_exec(&options_scope) : association_class.all
-        scope.limit(options_limit).map do |record|
-          [record.public_send(display_method), record.id]
+        scope = options_scope ? association_class.instance_exec(&options_scope) : association_adapter.all
+        association_adapter.limit(scope, options_limit).map do |record|
+          [option_label_for(record), record.id]
+        end
+      end
+
+      # @api private
+      # Resolves the option label for a single record. Mirrors
+      # `IronAdmin::ApplicationHelper#display_record_label` so callers
+      # who construct the component directly (or test it without
+      # rendering) get the same fallback behavior:
+      #
+      # 1. Try the explicit `display_method:` (`Proc` or `Symbol`/
+      #    `String`) and return it if it produces a non-blank value.
+      # 2. If the explicit method is absent or returns blank/nil, walk
+      #    `DISPLAY_METHOD_FALLBACKS` and return the first non-blank one.
+      # 3. Otherwise return `"<Model> #<id>"` so the option is at least
+      #    identifiable.
+      #
+      # @param record [Object] The associated record
+      # @return [String] The label
+      def option_label_for(record)
+        explicit = explicit_display_value(record)
+        return explicit if explicit.present?
+
+        DISPLAY_METHOD_FALLBACKS.each do |method|
+          value = record.public_send(method) if record.respond_to?(method)
+          return value if value.present?
         end
+
+        "#{record.class.model_name.human} ##{record.id}"
       end
 
       # @api private
       # @return [Boolean] Whether to show hint about more records available
       def show_search_hint?
-        association_class.count > options_limit
+        association_adapter.count > options_limit
       end
 
       # @api private
@@ -105,6 +142,23 @@ module IronAdmin
           "stroke-width='1.5' d='M6 8l4 4 4-4'/%3e%3c/svg%3e\"); background-position: right 0.5rem center; " \
           "background-repeat: no-repeat; background-size: 1.5em 1.5em; padding-right: 2.5rem;"
       end
+
+      private
+
+      # Calls the explicit `display_method:` (if any) and returns its
+      # result. Returns `nil` when no explicit method is set, so callers
+      # can `present?`-check and fall through to the auto-detect chain.
+      def explicit_display_value(record)
+        case display_method
+        when Proc then display_method.call(record)
+        when Symbol, String then record.public_send(display_method)
+        end
+      end
+
+      # @return [IronAdmin::Adapters::Base] Adapter for the associated model
+      def association_adapter
+        @association_adapter ||= IronAdmin::Adapters::ActiveRecord.new(association_class)
+      end
     end
   end
 end

data/app/components/iron_admin/form/nested_form_component.html.haml

@@ -0,0 +1,28 @@
+%div{ data: { controller: "cp-nested-form",
+            "cp-nested-form-association-name-value": name,
+            "cp-nested-form-allow-destroy-value": allow_destroy,
+            "cp-nested-form-sortable-value": sortable? } }
+
+  .flex.items-center.justify-between.mb-4
+    %h3.text-base.font-semibold{ class: "#{theme.heading_weight} #{theme.body_text}" }= title
+    - if show_add_button?
+      %button.inline-flex.items-center.gap-1.px-3.py-1.text-sm.font-medium.rounded-lg.border.border-dashed.cursor-pointer{ type: "button",
+        class: "#{theme.link} border-current hover:bg-gray-50",
+        data: { action: "cp-nested-form#addRow" } }
+        = I18n.t("iron_admin.nested_form.add_button", default: "Add row")
+
+  -# Hidden template for JS cloning of new rows
+  %template{ id: "#{name}-nested-template" }
+    - if form
+      - new_child = nested_association.reflection.klass.new
+      = form.fields_for name, new_child, child_index: template_index do |child_f|
+        = render "iron_admin/form/nested_row", child_f: child_f, nested_association: nested_association,
+          child: new_child, current_user: current_user
+
+  -# Existing rows container
+  %div{ data: { "cp-nested-form-target": "rowsContainer" } }
+    - child_records.each do |child|
+      - if form
+        = form.fields_for name, child do |child_f|
+          = render "iron_admin/form/nested_row", child_f: child_f, nested_association: nested_association,
+            child: child, current_user: current_user

data/app/components/iron_admin/form/nested_form_component.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Form
+    # ViewComponent for rendering nested association forms inline within a parent form.
+    #
+    # Renders existing child records as editable rows and provides a hidden <template>
+    # element that JavaScript clones to add new rows dynamically.
+    class NestedFormComponent < ViewComponent::Base
+      # @return [ActionView::Helpers::FormBuilder] The parent form builder
+      attr_reader :form
+
+      # @return [IronAdmin::NestedAssociation] The nested association configuration
+      attr_reader :nested_association
+
+      # @return [ActiveRecord::Base] The parent record
+      attr_reader :record
+
+      # @return [Object, nil] The current authenticated user
+      attr_reader :current_user
+
+      delegate :name, :kind, :fields, :allow_destroy, :position_field, to: :nested_association
+
+      # @param form [ActionView::Helpers::FormBuilder] The parent form builder
+      # @param nested_association [IronAdmin::NestedAssociation] Nested config
+      # @param record [ActiveRecord::Base] The parent record
+      # @param current_user [Object, nil] Current user for permission checks
+      def initialize(form:, nested_association:, record:, current_user: nil)
+        super()
+        @form = form
+        @nested_association = nested_association
+        @record = record
+        @current_user = current_user
+      end
+
+      # @return [IronAdmin::Configuration::Theme] Theme configuration
+      def theme
+        IronAdmin.configuration.theme
+      end
+
+      # @return [String] Human-readable title for the section header
+      def title
+        name.to_s.humanize
+      end
+
+      # @return [Boolean] Whether to show the "Add" button (has_many only)
+      def show_add_button?
+        kind == :has_many
+      end
+
+      # @return [Boolean] Whether drag-and-drop sorting is enabled
+      def sortable?
+        position_field.present?
+      end
+
+      # @return [String] The placeholder index used in template rows
+      def template_index
+        "NEW_RECORD_INDEX"
+      end
+
+      # Returns the child records for the nested association.
+      #
+      # For has_one, wraps the record in an array or builds a new instance.
+      # For has_many with a position_field, sorts by that field ascending.
+      # Returns in-memory objects so validation errors are preserved.
+      #
+      # @return [Array<ActiveRecord::Base>] Child records
+      def child_records
+        children = record.public_send(name)
+
+        if kind == :has_one
+          [children || nested_association.reflection.klass.new]
+        elsif position_field
+          children.to_a.sort_by { |c| c.public_send(position_field) || Float::INFINITY }
+        else
+          children.to_a
+        end
+      end
+    end
+  end
+end

data/app/components/iron_admin/resources/data_table_component.html.haml

@@ -23,7 +23,7 @@
             No records found.
     - else
       - records.each do |record|
-        %tr{ class: theme.table_row_hover }
+        %tr{ id: row_dom_id(record), class: theme.table_row_hover }
           - visible_fields.each do |field|
             %td.px-6.py-4.whitespace-nowrap.text-sm{ class: theme.body_text }
               = helpers.display_index_field_value(record, field)

data/app/components/iron_admin/resources/data_table_component.rb

@@ -89,6 +89,12 @@ module IronAdmin
       def sort_direction
         current_direction
       end
+
+      # @api private
+      # @return [String] Stable Turbo Stream target id for a record row
+      def row_dom_id(record)
+        "iron_admin_#{resource_class.resource_name}_row_#{record.id}"
+      end
     end
   end
 end

data/app/components/iron_admin/resources/show_field_component.rb

@@ -23,6 +23,8 @@ module IronAdmin
       end
 
       def render?
+        return false if field.type == :hidden
+
         field.visible?(@current_user)
       end
 

data/app/controllers/iron_admin/application_controller.rb

@@ -13,7 +13,10 @@ module IronAdmin
 
     before_action :authenticate_iron_admin_user!
 
-    helper_method :iron_admin_current_user
+    rescue_from IronAdmin::RecordNotFound, with: :render_not_found
+    rescue_from ActionController::ParameterMissing, with: :render_bad_request
+
+    helper_method :iron_admin_current_user, :iron_admin_filter_param, :iron_admin_active_filter?
 
     private
 
@@ -30,5 +33,33 @@ module IronAdmin
 
       @iron_admin_current_user ||= instance_exec(self, &IronAdmin.configuration.current_user_block)
     end
+
+    def iron_admin_filter_param(*keys)
+      iron_admin_param_dig(params[:filters], *keys)
+    end
+
+    def iron_admin_active_filter?(filter)
+      iron_admin_filter_param(filter[:name]).present? ||
+        iron_admin_filter_param("#{filter[:name]}_from").present? ||
+        iron_admin_filter_param("#{filter[:name]}_to").present? ||
+        (iron_admin_filter_param(filter[:name].to_s).is_a?(ActionController::Parameters) &&
+          iron_admin_filter_param(filter[:name].to_s, "value").present?)
+    end
+
+    def iron_admin_param_dig(value, *keys)
+      keys.reduce(value) do |current, key|
+        return nil unless current.is_a?(ActionController::Parameters) || current.is_a?(Hash)
+
+        current[key]
+      end
+    end
+
+    def render_not_found
+      head(:not_found)
+    end
+
+    def render_bad_request
+      head(:bad_request)
+    end
   end
 end

data/app/controllers/iron_admin/concerns/action_executable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Concerns
+    # Provides action execution with arity-based dispatch for form params.
+    #
+    # Supports both legacy 1-arg blocks (backward compat) and 2-arg blocks
+    # that receive collected action_form params as the second argument.
+    module ActionExecutable
+      extend ActiveSupport::Concern
+
+      private
+
+      # Dispatches an action block with the correct number of arguments.
+      #
+      # 1-arg blocks receive only the subject (record or records).
+      # 2-arg blocks receive the subject and collected form params.
+      #
+      # @param block [Proc] The action block
+      # @param subject [Object] The record or records
+      # @param collected_params [Hash] Collected form params
+      # @return [Object] The block's return value
+      def call_action_block(block, subject, collected_params)
+        if block.arity.in?([1, -1])
+          block.call(subject)
+        else
+          block.call(subject, collected_params)
+        end
+      end
+
+      # Extracts and permits action form params based on declared form_fields.
+      #
+      # @param action [Hash] The action definition with :form_fields key
+      # @return [Hash] Permitted params with symbolized keys, or empty hash
+      def action_form_params(action)
+        fields = action[:form_fields] || []
+        return {} if fields.empty?
+
+        permitted_keys = fields.map(&:name)
+        params.fetch(:action_form, {}).permit(*permitted_keys).to_h.symbolize_keys
+      end
+    end
+  end
+end

data/app/controllers/iron_admin/concerns/filterable.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Concerns
+    # Provides filter functionality for resource controllers.
+    #
+    # Supports flat filters (:select, :boolean), date range filters,
+    # and operator-based filters (:string, :number) via QueryBuilder.
+    module Filterable
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :iron_admin_visible_filters if respond_to?(:helper_method)
+      end
+
+      private
+
+      # Applies all configured filters to the scope.
+      #
+      # @param scope [Object] Base query scope (ActiveRecord::Relation or Mongoid::Criteria)
+      # @return [Object] Filtered scope
+      def apply_filters(scope)
+        iron_admin_visible_filters.each do |filter|
+          scope = case filter[:type]
+                  when :string, :number then apply_operator_filter(scope, filter)
+                  when :date_range then apply_date_range_filter(scope, filter)
+                  else apply_flat_filter(scope, filter)
+                  end
+        end
+        scope
+      end
+
+      def iron_admin_visible_filters
+        @iron_admin_visible_filters ||= begin
+          resolved_fields = @resource_class.resolved_fields
+          resolved_names = resolved_fields.map(&:name)
+          visible_names = resolved_fields.select { |field| field.visible?(iron_admin_current_user) }.map(&:name)
+
+          @resource_class.all_filters.select do |filter|
+            filter_name = filter[:name].to_sym
+            resolved_names.exclude?(filter_name) || visible_names.include?(filter_name)
+          end
+        end
+      end
+
+      def apply_operator_filter(scope, filter)
+        sub = iron_admin_filter_param(filter[:name].to_s)
+        return scope unless sub.is_a?(ActionController::Parameters) && sub["value"].present?
+
+        adapter.query_builder_class.call(scope, filter, sub.to_unsafe_h)
+      end
+
+      def apply_date_range_filter(scope, filter)
+        from = iron_admin_filter_param("#{filter[:name]}_from")
+        to = iron_admin_filter_param("#{filter[:name]}_to")
+        scope = adapter.filter(scope, filter[:name], parse_date(from)..) if from.present? && parse_date(from)
+        scope = adapter.filter(scope, filter[:name], ..parse_date(to)&.end_of_day) if to.present? && parse_date(to)
+        scope
+      end
+
+      def apply_flat_filter(scope, filter)
+        value = iron_admin_filter_param(filter[:name])
+        return scope if value.blank?
+        return scope unless value.is_a?(String)
+
+        value = adapter.cast_boolean(value) if filter[:type] == :boolean
+
+        if filter[:scope]
+          filter[:scope].call(value, scope)
+        else
+          adapter.filter(scope, filter[:name], value)
+        end
+      end
+
+      def parse_date(value)
+        return nil if value.blank?
+
+        Date.parse(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end