iron_admin 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0ecb90c4ba9e2c3f605ceae6041d3b73ba81ebf8cf39814d07a01d879c3a005
-  data.tar.gz: 36979178db1f62372e1ca1d660ad86c8696729db3cc6831326df7747789bb331
+  metadata.gz: cd7c68ca4e035fc4fe1b47d4c3415e76dcbb9ba77a53e9a574abe55a7e3bd6c9
+  data.tar.gz: 95ef292dd61db7778af10963a749cc63a9f67e9ecda2a8f115207522ffb28caf
 SHA512:
-  metadata.gz: e8dbf2accd69aa53038df74fb9e5a080581b9cd70d45cc5af806a13df2934ffe072da678ed81fb22c9b3354274e4997ccf5b335f5ac140eab3a54c55aaf8d697
-  data.tar.gz: d8d3fbf9c74c876dc85837ebbf5f767ae68eb3246e6fb543b17baf8e9d196a33b45505489660ff73816699de9054c2d7cc04611f78668af0af7ae754a07b6e66
+  metadata.gz: 056e8a6cf97e585a4d979e303aa2a9ca10618b50e6fb75a5f61d5c52070adb7d8d4ae65498eefad9346700eb8ad629a11203a8fc940bd0f96cf44065e2b02b3e
+  data.tar.gz: 419a9faf097e0a4f0beab00624eb7e79876cb1b6fbce0d61703dd13f3d879b102586d1271bb58073e7da1dd7cb0709776b625f9cfefaaac41881ecb9be79c259

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

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Concerns
+    # Coerces incoming `:json` form params from JSON strings (the textarea
+    # content rendered by `_form.html.haml`'s `when :json` branch) back into
+    # Ruby `Hash`/`Array`. Without this, the controller would assign the raw
+    # textarea string to the model's jsonb/json column, replacing the
+    # structured value with a string and silently losing data.
+    #
+    # Invalid JSON is left as-is so model-side validation can surface the
+    # error to the user instead of being swallowed.
+    module JsonParamsCoercion
+      extend ActiveSupport::Concern
+
+      private
+
+      def coerce_json_field_params!(parsed)
+        coerce_json_fields!(parsed, form_fields)
+        coerce_nested_json_field_params!(parsed)
+      end
+
+      def coerce_json_fields!(parsed, fields)
+        fields.each do |field|
+          next unless field.type == :json
+
+          value = parsed[field.name]
+          next unless value.is_a?(String)
+
+          # An empty textarea means "clear this field". Storing the empty
+          # string would serialize to a JSON string scalar (`""`) instead
+          # of clearing the column.
+          if value.empty?
+            parsed[field.name] = nil
+            next
+          end
+
+          parsed[field.name] = JSON.parse(value)
+        rescue JSON::ParserError
+          # Drop the key so the existing column value is preserved instead
+          # of being overwritten with the raw string (which AR would then
+          # store as a JSON string scalar, silently destroying the prior
+          # Hash/Array). The user keeps the form open via model-side
+          # validation in the typical case; full inline-error UX is tracked
+          # as a follow-up.
+          parsed.delete(field.name)
+        end
+      end
+
+      def coerce_nested_json_field_params!(parsed)
+        @resource_class.nested_associations.each do |nested|
+          nested_params = parsed[:"#{nested.name}_attributes"]
+          next unless nested_params.respond_to?(:each_value)
+
+          json_fields = nested.fields.select { |field| field.type == :json }
+          next if json_fields.empty?
+
+          child_params_collection = nested.kind == :has_many ? nested_params.each_value : [nested_params]
+
+          child_params_collection.each do |child_params|
+            coerce_json_fields!(child_params, json_fields)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module IronAdmin
+  module Concerns
+    # Provides nested attribute strong parameter building for resource controllers.
+    module NestedPermittable
+      extend ActiveSupport::Concern
+
+      private
+
+      # Builds the permit list for a nested association's attributes.
+      #
+      # Includes all non-readonly field names, :id for matching existing records,
+      # :_destroy when allow_destroy is true, and the position_field when present.
+      #
+      # @param nested [IronAdmin::NestedAssociation]
+      # @return [Array] Permit list for strong params
+      def build_nested_permit_list(nested)
+        nested_fields = nested.fields.reject { |f| f.readonly?(iron_admin_current_user) }
+        permit_list = nested_fields.flat_map { |f| nested_field_permit(f) }
+        permit_list << :id
+        permit_list << :_destroy if nested.allow_destroy
+        permit_list << nested.position_field if nested.position_field
+        permit_list
+      end
+
+      def nested_field_permit(field)
+        case field.type
+        when :belongs_to then field.options[:foreign_key]
+        when :files then { field.name => [] }
+        else field.name
+        end
+      end
+    end
+  end
+end