iron_admin 0.4.1 → 0.6.0

data/app/views/iron_admin/resources/bulk_action_form.html.haml

@@ -0,0 +1,62 @@
+= turbo_frame_tag "action-form-modal" do
+  .p-8.max-w-lg.mx-auto{ class: t.font_family }
+    %h2.text-xl.mb-6{ class: cp_heading }= @action[:name].to_s.humanize
+
+    = form_tag @form_url, method: :post, class: "space-y-4" do
+      - @form_fields.each do |field|
+        .space-y-1
+          %label.block.text-sm.font-medium{ class: cp_label_text, for: "action_form_#{field.name}" }
+            = field.label
+            - if field.required
+              %span.text-red-500 *
+
+          - case field.type
+          - when :text
+            = text_field_tag "action_form[#{field.name}]", field.default,
+              id: "action_form_#{field.name}",
+              class: cp_filter_input_class,
+              placeholder: field.placeholder,
+              required: field.required
+          - when :textarea
+            = text_area_tag "action_form[#{field.name}]", field.default,
+              id: "action_form_#{field.name}",
+              class: "#{cp_filter_input_class} h-24",
+              placeholder: field.placeholder,
+              required: field.required
+          - when :number
+            = number_field_tag "action_form[#{field.name}]", field.default,
+              id: "action_form_#{field.name}",
+              class: cp_filter_input_class,
+              placeholder: field.placeholder,
+              step: "any",
+              required: field.required
+          - when :boolean
+            .flex.items-center.gap-2
+              = check_box_tag "action_form[#{field.name}]", "1", field.default,
+                id: "action_form_#{field.name}",
+                class: "rounded border-gray-300"
+              %span.text-sm{ class: cp_body_text }= field.label
+          - when :date
+            = date_field_tag "action_form[#{field.name}]", field.default,
+              id: "action_form_#{field.name}",
+              class: cp_filter_input_class,
+              required: field.required
+          - when :datetime
+            = datetime_field_tag "action_form[#{field.name}]", field.default,
+              id: "action_form_#{field.name}",
+              class: cp_filter_input_class,
+              required: field.required
+          - when :select
+            %select{ name: "action_form[#{field.name}]", id: "action_form_#{field.name}",
+              class: cp_filter_input_class, required: field.required }
+              %option{ value: "" }= field.placeholder || "Select..."
+              - (field.options || []).each do |opt|
+                %option{ value: opt, selected: field.default == opt }= opt.to_s.humanize
+
+      - if params[:ids].present?
+        - Array(params[:ids]).each do |id|
+          = hidden_field_tag "ids[]", id
+
+      .flex.items-center.gap-3.pt-3.border-t.border-gray-100
+        %button{ type: "submit", class: cp_btn_primary }= I18n.t("iron_admin.resources.action_form.submit", default: "Execute")
+        = link_to I18n.t("iron_admin.form.cancel_button"), "javascript:history.back()", class: "text-sm #{cp_link_muted}"

data/app/views/iron_admin/resources/index.html.haml

@@ -1,10 +1,18 @@
+- filters = iron_admin_visible_filters
+
 .p-8.max-w-7xl.mx-auto{ class: t.font_family }
   .flex.items-center.justify-between.mb-6
     %h1.text-2xl{ class: cp_heading }= @resource_class.label
-    - if @resource_class.action_allowed?(:create)
-      = link_to I18n.t("iron_admin.resources.index.new_button", model: @resource_class.model.model_name.human),
-        new_resource_path(@resource_class.resource_name),
-        class: cp_btn_primary
+    .flex.items-center.gap-2
+      - if @resource_class.import_enabled? && @resource_class.action_allowed?(:create)
+        = link_to resource_import_path(@resource_class.resource_name),
+          class: cp_btn_secondary do
+          = heroicon "arrow-up-tray", variant: :mini, options: { class: "h-4 w-4" }
+          %span= I18n.t("iron_admin.resources.index.import_button")
+      - if @resource_class.action_allowed?(:create)
+        = link_to I18n.t("iron_admin.resources.index.new_button", model: @resource_class.model.model_name.human),
+          new_resource_path(@resource_class.resource_name),
+          class: cp_btn_primary
 
   - if @resource_class.all_scopes.any? || @resource_class.searchable_columns.any?
     .flex.items-center.justify-between.mb-4
@@ -19,10 +27,18 @@
       - if @resource_class.searchable_columns.any?
         = form_tag resources_path(@resource_class.resource_name), method: :get, class: "flex ml-auto" do
           = hidden_field_tag :scope, @current_scope
-          - @resource_class.defined_filters.each do |filter|
-            - value = params.dig(:filters, filter[:name])
-            - if value.present?
-              = hidden_field_tag "filters[#{filter[:name]}]", value
+          - filters.each do |filter|
+            - if filter[:type].in?(%i[string number])
+              - sub = iron_admin_filter_param(filter[:name].to_s)
+              - if sub.is_a?(ActionController::Parameters) && sub["value"].present?
+                = hidden_field_tag "filters[#{filter[:name]}][op]", sub["op"]
+                = hidden_field_tag "filters[#{filter[:name]}][value]", sub["value"]
+                - if sub["value_2"].present?
+                  = hidden_field_tag "filters[#{filter[:name]}][value_2]", sub["value_2"]
+            - else
+              - value = iron_admin_filter_param(filter[:name])
+              - if value.present?
+                = hidden_field_tag "filters[#{filter[:name]}]", value
           .relative
             .pointer-events-none.absolute.inset-y-0.left-0.flex.items-center{ class: "pl-3.5" }
               = heroicon "magnifying-glass", variant: :mini, options: { class: "h-4 w-4 #{cp_muted_text}" }
@@ -30,8 +46,8 @@
               placeholder: I18n.t("iron_admin.resources.index.search_placeholder"),
               class: cp_search_class
 
-  - if @resource_class.defined_filters.any?
-    - has_active_filters = @resource_class.defined_filters.any? { |f| params.dig(:filters, f[:name]).present? || params.dig(:filters, "#{f[:name]}_from").present? || params.dig(:filters, "#{f[:name]}_to").present? }
+  - if filters.any?
+    - has_active_filters = filters.any? { |f| iron_admin_active_filter?(f) }
     - select_chevron_style = "background-image: url(\"data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' fill='none' viewBox='0 0 20 20'%3e%3cpath stroke='%236b7280' stroke-linecap='round' stroke-linejoin='round' 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;"
     .flex.justify-end.mb-4
       %details.relative.group{ open: has_active_filters || nil }
@@ -39,7 +55,7 @@
           = heroicon "funnel", variant: :mini, options: { class: "h-4 w-4 #{cp_muted_text}" }
           %span= I18n.t("iron_admin.resources.index.filters_label")
           - if has_active_filters
-            - active_count = @resource_class.defined_filters.count { |f| params.dig(:filters, f[:name]).present? || params.dig(:filters, "#{f[:name]}_from").present? || params.dig(:filters, "#{f[:name]}_to").present? }
+            - active_count = filters.count { |f| iron_admin_active_filter?(f) }
             %span{ class: cp_badge_count }
               = active_count
           = heroicon "chevron-down", variant: :mini, options: { class: "h-4 w-4 text-gray-400 transition-transform group-open:rotate-180" }
@@ -48,7 +64,7 @@
             = hidden_field_tag :scope, @current_scope
             = hidden_field_tag :q, params[:q]
             .space-y-3
-              - @resource_class.defined_filters.each do |filter|
+              - filters.each do |filter|
                 .space-y-1
                   %label.block.text-xs.font-semibold.uppercase.tracking-wider{ class: cp_muted_text }
                     = filter[:name].to_s.humanize
@@ -57,20 +73,47 @@
                     %select.block.w-full.appearance-none.border.px-3.py-2.text-sm.shadow-sm.outline-none.transition.duration-150.ease-in-out{ name: "filters[#{filter[:name]}]", class: "#{t.border_radius} #{t.input_border} #{t.card_bg} #{cp_body_text} #{cp_focus}", style: select_chevron_style }
                       %option{ value: "" }= I18n.t("iron_admin.resources.index.all_option")
                       - filter_options_for(@resource_class, filter).each do |label, value|
-                        %option{ value: value, selected: params.dig(:filters, filter[:name]) == value.to_s }= label
+                        %option{ value: value, selected: iron_admin_filter_param(filter[:name]) == value.to_s }= label
                   - when :boolean
                     %select.block.w-full.appearance-none.border.px-3.py-2.text-sm.shadow-sm.outline-none.transition.duration-150.ease-in-out{ name: "filters[#{filter[:name]}]", class: "#{t.border_radius} #{t.input_border} #{t.card_bg} #{cp_body_text} #{cp_focus}", style: select_chevron_style }
                       %option{ value: "" }= I18n.t("iron_admin.resources.index.all_option")
                       - filter_options_for(@resource_class, filter).each do |label, value|
-                        %option{ value: value, selected: params.dig(:filters, filter[:name]) == value.to_s }= label
+                        %option{ value: value, selected: iron_admin_filter_param(filter[:name]) == value.to_s }= label
                   - when :date_range
                     .space-y-2
-                      = date_field_tag "filters[#{filter[:name]}_from]", params.dig(:filters, "#{filter[:name]}_from"),
+                      = date_field_tag "filters[#{filter[:name]}_from]", iron_admin_filter_param("#{filter[:name]}_from"),
                         class: cp_filter_input_class,
                         placeholder: I18n.t("iron_admin.filters.from")
-                      = date_field_tag "filters[#{filter[:name]}_to]", params.dig(:filters, "#{filter[:name]}_to"),
+                      = date_field_tag "filters[#{filter[:name]}_to]", iron_admin_filter_param("#{filter[:name]}_to"),
                         class: cp_filter_input_class,
                         placeholder: I18n.t("iron_admin.filters.to")
+                  - when :string
+                    - string_ops = %w[contains equals starts_with ends_with]
+                    - current_op = iron_admin_filter_param(filter[:name].to_s, "op") || "contains"
+                    - current_val = iron_admin_filter_param(filter[:name].to_s, "value") || ""
+                    .space-y-2
+                      %select.block.w-full.appearance-none.border.px-3.py-2.text-sm.shadow-sm.outline-none.transition.duration-150.ease-in-out{ name: "filters[#{filter[:name]}][op]", class: "#{t.border_radius} #{t.input_border} #{t.card_bg} #{cp_body_text} #{cp_focus}", style: select_chevron_style }
+                        - string_ops.each do |op|
+                          %option{ value: op, selected: current_op == op }= I18n.t("iron_admin.filters.operators.#{op}")
+                      = text_field_tag "filters[#{filter[:name]}][value]", current_val,
+                        class: cp_filter_input_class,
+                        placeholder: filter[:label] || filter[:name].to_s.humanize
+                  - when :number
+                    - number_ops = %w[equals greater_than less_than between]
+                    - current_op = iron_admin_filter_param(filter[:name].to_s, "op") || "equals"
+                    - current_val = iron_admin_filter_param(filter[:name].to_s, "value") || ""
+                    - current_val_upper = iron_admin_filter_param(filter[:name].to_s, "value_2") || ""
+                    .space-y-2{ data: { controller: "filter-operator" } }
+                      %select.block.w-full.appearance-none.border.px-3.py-2.text-sm.shadow-sm.outline-none.transition.duration-150.ease-in-out{ name: "filters[#{filter[:name]}][op]", class: "#{t.border_radius} #{t.input_border} #{t.card_bg} #{cp_body_text} #{cp_focus}", style: select_chevron_style, data: { action: "change->filter-operator#toggle", filter_operator_target: "opSelect" } }
+                        - number_ops.each do |op|
+                          %option{ value: op, selected: current_op == op }= I18n.t("iron_admin.filters.operators.#{op}")
+                      = number_field_tag "filters[#{filter[:name]}][value]", current_val,
+                        class: cp_filter_input_class, step: "any",
+                        placeholder: filter[:label] || filter[:name].to_s.humanize
+                      .flex.items-center.gap-2{ data: { filter_operator_target: "betweenRow" }, class: current_op == "between" ? "" : "hidden" }
+                        %span.text-xs{ class: cp_muted_text }= I18n.t("iron_admin.filters.between_separator")
+                        = number_field_tag "filters[#{filter[:name]}][value_2]", current_val_upper,
+                          class: cp_filter_input_class, step: "any"
             .flex.items-center.gap-3.mt-4.pt-3.border-t.border-gray-100
               %button{ type: "submit", class: cp_btn_filter_apply }= I18n.t("iron_admin.resources.index.apply_button")
               = link_to I18n.t("iron_admin.resources.index.clear_button"), resources_path(@resource_class.resource_name, scope: @current_scope, q: params[:q]),
@@ -122,7 +165,7 @@
                 %td.px-6.py-8.text-center.text-sm{ colspan: (@fields.count { |f| f.visible?(iron_admin_current_user) }) + (has_bulk_actions ? 2 : 1), class: cp_muted_text }
                   = I18n.t("iron_admin.resources.index.empty_state")
             - @records.each do |record|
-              %tr{ class: cp_table_row_hover }
+              %tr{ id: ("iron_admin_#{@resource_class.resource_name}_row_#{record.id}" if @resource_class.live_index_enabled?), class: cp_table_row_hover }
                 - if has_bulk_actions
                   %td.px-6.py-4.w-4
                     %input{ type: "checkbox", name: "ids[]", value: record.id, class: "rounded border-gray-300",
@@ -137,4 +180,3 @@
 
     .mt-4
       = render "iron_admin/shared/pagination", pagy: @pagy
-

data/app/views/iron_admin/tools/action_form.html.haml

@@ -0,0 +1,57 @@
+.p-8.max-w-lg.mx-auto{ class: t.font_family }
+  %h2.text-xl.mb-6{ class: cp_heading }= @declared_action.label
+
+  = form_tag @form_url, method: :post, class: "space-y-4" do
+    - @form_fields.each do |field|
+      .space-y-1
+        %label.block.text-sm.font-medium{ class: cp_label_text, for: "tool_action_#{field.name}" }
+          = field.label
+          - if field.required
+            %span.text-red-500 *
+
+        - case field.type
+        - when :text
+          = text_field_tag "tool_action[#{field.name}]", field.default,
+            id: "tool_action_#{field.name}",
+            class: cp_filter_input_class,
+            placeholder: field.placeholder,
+            required: field.required
+        - when :textarea
+          = text_area_tag "tool_action[#{field.name}]", field.default,
+            id: "tool_action_#{field.name}",
+            class: "#{cp_filter_input_class} h-24",
+            placeholder: field.placeholder,
+            required: field.required
+        - when :number
+          = number_field_tag "tool_action[#{field.name}]", field.default,
+            id: "tool_action_#{field.name}",
+            class: cp_filter_input_class,
+            placeholder: field.placeholder,
+            step: "any",
+            required: field.required
+        - when :boolean
+          .flex.items-center.gap-2
+            = check_box_tag "tool_action[#{field.name}]", "1", field.default,
+              id: "tool_action_#{field.name}",
+              class: "rounded border-gray-300"
+            %span.text-sm{ class: cp_body_text }= field.label
+        - when :date
+          = date_field_tag "tool_action[#{field.name}]", field.default,
+            id: "tool_action_#{field.name}",
+            class: cp_filter_input_class,
+            required: field.required
+        - when :datetime
+          = datetime_field_tag "tool_action[#{field.name}]", field.default,
+            id: "tool_action_#{field.name}",
+            class: cp_filter_input_class,
+            required: field.required
+        - when :select
+          %select{ name: "tool_action[#{field.name}]", id: "tool_action_#{field.name}",
+            class: cp_filter_input_class, required: field.required }
+            %option{ value: "" }= field.placeholder || "Select..."
+            - (field.options || []).each do |opt|
+              %option{ value: opt, selected: field.default == opt }= opt.to_s.humanize
+
+    .flex.items-center.gap-3.pt-3.border-t.border-gray-100
+      %button{ type: "submit", class: cp_btn_primary }= I18n.t("iron_admin.tools.action_form.submit", default: "Execute")
+      = link_to I18n.t("iron_admin.form.cancel_button"), tool_path(@tool_class.tool_name), class: "text-sm #{cp_link_muted}"

data/app/views/iron_admin/tools/show.html.haml

@@ -3,5 +3,24 @@
     %h1.text-2xl{ class: cp_heading }= @tool_class.label
   .overflow-hidden{ class: cp_card }
     .p-6
-      %p.text-sm{ class: cp_muted_text }
+      %p.text-sm.mb-6{ class: cp_muted_text }
         = @tool_class.label
+
+      - if @tool_class.defined_tool_actions.any?
+        .space-y-3
+          - @tool_class.defined_tool_actions.each do |action|
+            - next unless action.allowed?(iron_admin_current_user)
+            - if action.has_form?
+              = link_to tool_action_form_path(@tool_class.tool_name, action.name),
+                class: "#{t.btn_secondary} px-4 py-2 text-sm font-medium rounded-lg inline-flex items-center gap-2" do
+                - if action.icon
+                  = heroicon action.icon, variant: :mini, options: { class: "h-4 w-4" }
+                = action.label
+            - else
+              = button_to tool_action_path(@tool_class.tool_name, action.name),
+                method: :post,
+                class: "#{t.btn_secondary} px-4 py-2 text-sm font-medium rounded-lg inline-flex items-center gap-2",
+                data: action.confirm ? { turbo_confirm: action.confirm_message || I18n.t("iron_admin.tools.confirm_default", default: "Are you sure?") } : {} do
+                - if action.icon
+                  = heroicon action.icon, variant: :mini, options: { class: "h-4 w-4" }
+                = action.label

data/config/importmap.rb

@@ -9,3 +9,5 @@ pin "@rails/actiontext", to: "actiontext.esm.js"
 pin "iron_admin", to: "iron_admin/index.js"
 pin "iron_admin/controllers/cp_bulk_select_controller", to: "iron_admin/controllers/cp_bulk_select_controller.js"
 pin "iron_admin/controllers/cp_chart_controller", to: "iron_admin/controllers/cp_chart_controller.js"
+pin "iron_admin/controllers/cp_nested_form_controller", to: "iron_admin/controllers/cp_nested_form_controller.js"
+pin "iron_admin/controllers/filter_operator_controller", to: "iron_admin/controllers/filter_operator_controller.js"

data/config/locales/en.yml

@@ -17,6 +17,7 @@ en:
         inaccessible: "Some records are not accessible"
       index:
         new_button: "New %{model}"
+        import_button: "Import"
         search_placeholder: "Search..."
         filters_label: "Filters"
         apply_button: "Apply"
@@ -36,6 +37,25 @@ en:
         view_link: "View"
         view_all: "View all"
         actions_label: "Actions"
+    imports:
+      new:
+        title: "Import %{model}"
+        subtitle: "Upload CSV or JSON data and preview mapped rows before importing."
+        file_label: "File"
+        format_label: "Format"
+        fields_label: "Importable fields"
+        preview_button: "Preview"
+      preview:
+        title: "Preview %{model} Import"
+        summary: "%{count} rows detected."
+        mapping_title: "Column mapping"
+        status_column: "Status"
+        valid_status: "Valid"
+        back_button: "Back"
+      create:
+        success: "Import finished: %{created} created, %{updated} updated, %{failed} failed."
+      errors:
+        missing_file: "Choose a file to import."
     fields:
       select_placeholder: "Select..."
       boolean_enable: "Enable %{field}"
@@ -47,12 +67,28 @@ en:
       color_placeholder: "#000000"
       number_placeholder: "0"
       currency_placeholder: "0.00"
+      radio_placeholder: "Select an option"
+      code_placeholder: "Enter code..."
+      key_value_placeholder: '{"key": "value"}'
+      progress_placeholder: "0"
     form:
       cancel_button: "Cancel"
     navigation:
       dashboard: "Dashboard"
+    nested_form:
+      add_button: "Add row"
+      remove_button: "Remove"
     filters:
       "true": "Yes"
       "false": "No"
       from: "From"
       to: "To"
+      operators:
+        contains: "Contains"
+        equals: "Equals"
+        starts_with: "Starts with"
+        ends_with: "Ends with"
+        greater_than: "Greater than"
+        less_than: "Less than"
+        between: "Between"
+      between_separator: "and"

data/config/routes.rb

@@ -3,16 +3,23 @@ IronAdmin::Engine.routes.draw do
 
   get "search", to: "search#index", as: :search
   get "audit", to: "audit#index", as: :audit
+  get "live/:stream", to: "live#show", as: :live
   get "autocomplete/:resource_name", to: "resources#autocomplete", as: :autocomplete
   get ":resource_name/export", to: "exports#show", as: :export
+  get ":resource_name/import", to: "imports#new", as: :resource_import
+  post ":resource_name/import/preview", to: "imports#preview", as: :resource_import_preview
+  post ":resource_name/import", to: "imports#create"
 
   get "tools/:tool_name", to: "tools#show", as: :tool
+  get "tools/:tool_name/:action_name/form", to: "tools#action_form", as: :tool_action_form
   post "tools/:tool_name/:action_name", to: "tools#execute", as: :tool_action
 
+  get ":resource_name/bulk_actions/:action_name/form", to: "resources#bulk_action_form", as: :resource_bulk_action_form
   get ":resource_name", to: "resources#index", as: :resources
   get ":resource_name/new", to: "resources#new", as: :new_resource
   get ":resource_name/:id", to: "resources#show", as: :resource
   get ":resource_name/:id/edit", to: "resources#edit", as: :edit_resource
+  get ":resource_name/:id/actions/:action_name/form", to: "resources#action_form", as: :resource_action_form
   post ":resource_name", to: "resources#create"
   patch ":resource_name/:id", to: "resources#update"
   delete ":resource_name/:id", to: "resources#destroy"

data/docs/components/filter-components.md

@@ -80,6 +80,66 @@ IronAdmin::Filters::DateRangeComponent.new(
 
 ---
 
+## StringFilterComponent
+
+Text input with an operator dropdown for string matching.
+
+```ruby
+IronAdmin::Filters::StringFilterComponent.new(
+  name: :name,                   # Required: filter parameter name
+  label: nil,                    # Optional: label text (auto-generated from name)
+  value: nil,                    # Optional: current filter value
+  operator: "contains"           # Optional: current operator (default: "contains")
+)
+```
+
+**Operators:** `contains`, `equals`, `starts_with`, `ends_with`
+
+**Example:**
+
+```haml
+= render IronAdmin::Filters::StringFilterComponent.new(
+  name: :name,
+  label: "Customer Name",
+  value: params.dig(:filters, :name),
+  operator: params.dig(:filters, :name_operator) || "contains"
+)
+```
+
+---
+
+## NumberFilterComponent
+
+Number input with an operator dropdown for numeric comparisons.
+
+```ruby
+IronAdmin::Filters::NumberFilterComponent.new(
+  name: :price,                  # Required: filter parameter name
+  label: nil,                    # Optional: label text (auto-generated from name)
+  value: nil,                    # Optional: current filter value
+  max_value: nil,                # Optional: upper bound for "between" operator
+  operator: "equals"             # Optional: current operator (default: "equals")
+)
+```
+
+**Operators:** `equals`, `greater_than`, `less_than`, `between`
+
+When the `between` operator is selected, a second input for the upper bound is displayed.
+
+**Example:**
+
+```haml
+= render IronAdmin::Filters::NumberFilterComponent.new(
+  name: :price,
+  label: "Price",
+  value: params.dig(:filters, :price),
+  max_value: params.dig(:filters, :price_max),
+  operator: params.dig(:filters, :price_operator) || "equals"
+)
+```
+
+---
+
 ## BarComponent
 
 Container for filter controls with dropdown behavior.

data/docs/getting-started/installation.md

@@ -4,18 +4,15 @@
 
 - Ruby >= 3.2
 - Rails >= 7.1
-- Tailwind CSS (for default theme classes)
+- [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) >= 4.0
 
-## Step 1: Add the Gem
+## Step 1: Add the Gems
 
-Add IronAdmin to your `Gemfile`:
+Add IronAdmin and `tailwindcss-rails` to your `Gemfile`:
 
 ```ruby
-# From a local path:
-gem "iron_admin", path: "/path/to/iron_admin"
-
-# Or if published to a gem server:
 gem "iron_admin"
+gem "tailwindcss-rails"
 ```
 
 Then run:
@@ -35,11 +32,13 @@ This creates:
 | File | Purpose |
 |------|---------|
 | `config/initializers/iron_admin.rb` | Main configuration (title, auth, theme) |
-| `app/iron_admin/dashboards/` | Directory for dashboard definitions |
 | `app/iron_admin/resources/` | Directory for resource definitions |
-| `app/iron_admin/dashboard.rb` | Default dashboard class |
+| `app/iron_admin/dashboards/` | Directory for dashboard definitions |
+| `app/iron_admin/dashboards/admin_dashboard.rb` | Default dashboard class |
 
-It also mounts the engine in `config/routes.rb`.
+It also:
+- Mounts the engine at `/admin` in `config/routes.rb`
+- Adds the IronAdmin CSS import to `app/assets/tailwind/application.css`
 
 ## Step 3: Mount the Engine (if not auto-mounted)
 
@@ -79,9 +78,107 @@ rails generate iron_admin:resource User
 
 This creates `app/iron_admin/resources/user_resource.rb`. IronAdmin automatically infers fields from your model's database schema.
 
-## Step 6: Visit the Admin Panel
+## Step 6: Build CSS and Start the Server
+
+```bash
+rails tailwindcss:build
+bin/rails server
+```
+
+Visit `/admin` and your admin panel is ready.
+
+For development with live CSS recompilation, use `bin/dev` (which runs
+`tailwindcss:watch` alongside the Rails server via foreman).
+
+> **Note:** There is a [known issue](https://github.com/rails/tailwindcss-rails/issues/602)
+> in `tailwindcss-rails` v4 where `bin/dev` exits immediately after
+> starting. If this happens, edit `Procfile.dev` and change the CSS line
+> to `css: bin/rails tailwindcss:watch[always]`. See
+> [Troubleshooting](../guides/troubleshooting.md#bindev-exits-immediately-after-starting)
+> for details.
+
+## Tailwind CSS Setup
+
+IronAdmin uses Tailwind CSS v4 for all styling via the `tailwindcss-rails` gem.
+Understanding how the CSS pipeline works will help you troubleshoot any styling issues.
+
+### How it works
+
+1. IronAdmin ships with `@source` directives at `app/assets/tailwind/iron_admin/engine.css`
+   inside the gem. These tell the Tailwind compiler where to scan for CSS utility classes
+   used by the engine's views, components, and helpers.
+
+2. When `tailwindcss:build` runs, it first executes `tailwindcss:engines`. This task
+   detects IronAdmin's engine CSS and creates a bridge file at
+   `app/assets/builds/tailwind/iron_admin.css` containing an `@import` that points
+   to the engine's CSS.
+
+3. Your `app/assets/tailwind/application.css` must import this bridge file:
+
+   ```css
+   @import "tailwindcss";
+   @import "../builds/tailwind/iron_admin";
+   ```
+
+4. The Tailwind compiler processes `application.css`, follows the imports, scans all
+   the engine's source files via the `@source` directives, and generates the final
+   `app/assets/builds/tailwind.css` with all necessary utility classes.
+
+5. The engine's layout references `stylesheet_link_tag "tailwind"`, which serves
+   this compiled CSS file.
+
+### Manual setup (without the generator)
+
+If you didn't use the install generator, or the import line is missing:
 
-Start your server and navigate to `/admin`.
+1. Verify `tailwindcss-rails` is in your Gemfile and installed
+2. Add the import to `app/assets/tailwind/application.css`:
+
+   ```css
+   @import "tailwindcss";
+   @import "../builds/tailwind/iron_admin";
+   ```
+
+3. Build the CSS:
+
+   ```bash
+   rails tailwindcss:build
+   ```
+
+4. Verify the build output:
+
+   ```bash
+   ls -la app/assets/builds/tailwind.css
+   # Should be ~30KB+ (not ~6KB which indicates no utility classes)
+   ```
+
+### Troubleshooting
+
+**Styles not loading (unstyled admin panel)**
+
+This almost always means the Tailwind compiler didn't scan IronAdmin's source files.
+Check:
+
+1. The `@import "../builds/tailwind/iron_admin"` line exists in
+   `app/assets/tailwind/application.css`
+2. The bridge file exists at `app/assets/builds/tailwind/iron_admin.css`
+   (run `rails tailwindcss:build` to regenerate it)
+3. The compiled CSS at `app/assets/builds/tailwind.css` is large enough
+   (~30KB+, not ~6KB)
+
+**Bridge file not generated**
+
+If `app/assets/builds/tailwind/iron_admin.css` doesn't exist after running
+`rails tailwindcss:build`:
+
+- Ensure `tailwindcss-rails` >= 4.0 is installed (`bundle info tailwindcss-rails`)
+- Ensure `iron_admin` is properly loaded (check `bundle info iron_admin`)
+- Try running `rails tailwindcss:engines` directly
+
+**Styles disappear after bundle update**
+
+The bridge file uses an absolute path to the gem's CSS. After updating the gem
+(which changes the gem path), run `rails tailwindcss:build` to regenerate it.
 
 ## Dependencies
 
@@ -97,19 +194,8 @@ IronAdmin depends on the following gems (installed automatically):
 | `haml-rails` | >= 2.0 | Template engine |
 | `heroicon` | >= 1.0 | SVG icons |
 
-## Tailwind CSS Setup
-
-IronAdmin uses Tailwind CSS classes for all styling. Ensure your Tailwind configuration includes the engine's view paths in the `content` array so that all CSS classes are properly compiled.
+**Peer dependency** (must be added to your Gemfile manually):
 
-Add the path to the engine's app directory in your `tailwind.config.js`:
-
-```js
-module.exports = {
-  content: [
-    // ... your app paths
-    "./path/to/iron_admin/app/**/*.{rb,haml}",
-  ],
-}
-```
-
-If installed as a gem, use `bundle show iron_admin` to find the installed path and add it to your Tailwind content paths.
+| Gem | Version | Purpose |
+|-----|---------|---------|
+| `tailwindcss-rails` | >= 4.0 | Tailwind CSS compilation |

data/docs/getting-started/quick-start.md

@@ -1,6 +1,15 @@
 # Quick Start
 
-Get a full admin panel running in 5 steps.
+Get a full admin panel running in 6 steps.
+
+## Prerequisites
+
+IronAdmin uses [Tailwind CSS](https://tailwindcss.com/) for all styling and requires `tailwindcss-rails` >= 4.0. Ensure your application has a supported version installed:
+
+```bash
+bundle add tailwindcss-rails --version ">= 4.0"
+rails tailwindcss:install
+```
 
 ## 1. Install
 
@@ -81,4 +90,11 @@ class AdminDashboard < IronAdmin::Dashboard
 end
 ```
 
+## 6. Build CSS and Start
+
+```bash
+rails tailwindcss:build
+bin/rails server
+```
+
 Visit `/admin` and your admin panel is ready.