iron_admin 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +129 -1
  3. data/README.md +48 -1
  4. data/UPGRADING.md +495 -8
  5. data/app/assets/tailwind/iron_admin/engine.css +79 -4
  6. data/app/components/iron_admin/dashboards/activity_feed_component/item_component.html.haml +6 -9
  7. data/app/components/iron_admin/dashboards/activity_feed_component.html.haml +6 -5
  8. data/app/components/iron_admin/dashboards/activity_feed_component.rb +21 -24
  9. data/app/components/iron_admin/dashboards/chart_component.html.haml +3 -5
  10. data/app/components/iron_admin/dashboards/chart_component.rb +86 -24
  11. data/app/components/iron_admin/dashboards/concerns/themed_card.rb +39 -0
  12. data/app/components/iron_admin/dashboards/metric_card_component.html.haml +8 -7
  13. data/app/components/iron_admin/dashboards/metric_card_component.rb +2 -0
  14. data/app/components/iron_admin/dashboards/progress_component.html.haml +11 -7
  15. data/app/components/iron_admin/dashboards/progress_component.rb +11 -6
  16. data/app/components/iron_admin/dashboards/quick_links_component/link_component.html.haml +8 -9
  17. data/app/components/iron_admin/dashboards/quick_links_component.html.haml +6 -5
  18. data/app/components/iron_admin/dashboards/quick_links_component.rb +4 -12
  19. data/app/components/iron_admin/dashboards/recent_table_component.html.haml +15 -10
  20. data/app/components/iron_admin/dashboards/recent_table_component.rb +49 -0
  21. data/app/components/iron_admin/dashboards/stats_grid_component/stat_component.html.haml +13 -14
  22. data/app/components/iron_admin/dashboards/stats_grid_component.html.haml +1 -0
  23. data/app/components/iron_admin/dashboards/stats_grid_component.rb +9 -11
  24. data/app/components/iron_admin/filters/bar_component.html.haml +8 -6
  25. data/app/components/iron_admin/filters/bar_component.rb +56 -9
  26. data/app/components/iron_admin/filters/control_styles.rb +82 -0
  27. data/app/components/iron_admin/filters/date_range_component.html.haml +9 -4
  28. data/app/components/iron_admin/filters/date_range_component.rb +10 -6
  29. data/app/components/iron_admin/filters/search_component.html.haml +4 -4
  30. data/app/components/iron_admin/filters/search_component.rb +3 -5
  31. data/app/components/iron_admin/filters/select_filter_component.html.haml +1 -1
  32. data/app/components/iron_admin/filters/select_filter_component.rb +5 -16
  33. data/app/components/iron_admin/form/belongs_to_autocomplete_component.html.haml +9 -5
  34. data/app/components/iron_admin/form/belongs_to_autocomplete_component.rb +10 -8
  35. data/app/components/iron_admin/form/belongs_to_component.html.haml +2 -2
  36. data/app/components/iron_admin/form/belongs_to_component.rb +4 -18
  37. data/app/components/iron_admin/form/checkbox_component.rb +2 -3
  38. data/app/components/iron_admin/form/concerns/form_input_behavior.rb +1 -1
  39. data/app/components/iron_admin/form/control_classes.rb +108 -0
  40. data/app/components/iron_admin/form/date_picker_component.rb +3 -7
  41. data/app/components/iron_admin/form/field_wrapper_component.html.haml +3 -3
  42. data/app/components/iron_admin/form/field_wrapper_component.rb +3 -3
  43. data/app/components/iron_admin/form/nested_form_component.html.haml +4 -5
  44. data/app/components/iron_admin/form/nested_form_component.rb +12 -2
  45. data/app/components/iron_admin/form/select_component.html.haml +1 -1
  46. data/app/components/iron_admin/form/select_component.rb +2 -16
  47. data/app/components/iron_admin/form/text_input_component.rb +1 -5
  48. data/app/components/iron_admin/form/textarea_component.rb +1 -5
  49. data/app/components/iron_admin/layout/flash_component.html.haml +1 -1
  50. data/app/components/iron_admin/layout/flash_component.rb +4 -3
  51. data/app/components/iron_admin/layout/navbar_component.html.haml +15 -9
  52. data/app/components/iron_admin/layout/navbar_component.rb +29 -1
  53. data/app/components/iron_admin/layout/shell_component.html.haml +4 -4
  54. data/app/components/iron_admin/layout/shell_component.rb +16 -3
  55. data/app/components/iron_admin/layout/sidebar_component.html.haml +21 -25
  56. data/app/components/iron_admin/layout/sidebar_component.rb +76 -1
  57. data/app/components/iron_admin/layout/theme_switcher_component.html.haml +15 -0
  58. data/app/components/iron_admin/layout/theme_switcher_component.rb +74 -0
  59. data/app/components/iron_admin/resources/actions_component.html.haml +15 -8
  60. data/app/components/iron_admin/resources/actions_component.rb +34 -2
  61. data/app/components/iron_admin/resources/breadcrumb_component.html.haml +3 -3
  62. data/app/components/iron_admin/resources/breadcrumb_component.rb +8 -7
  63. data/app/components/iron_admin/resources/bulk_actions_component.html.haml +9 -8
  64. data/app/components/iron_admin/resources/bulk_actions_component.rb +47 -4
  65. data/app/components/iron_admin/resources/data_table_component.html.haml +15 -15
  66. data/app/components/iron_admin/resources/data_table_component.rb +34 -3
  67. data/app/components/iron_admin/resources/related_list_component.html.haml +7 -7
  68. data/app/components/iron_admin/resources/related_list_component.rb +26 -2
  69. data/app/components/iron_admin/resources/show_field_component.html.haml +3 -3
  70. data/app/components/iron_admin/resources/show_field_component.rb +10 -4
  71. data/app/components/iron_admin/resources/styles.rb +136 -0
  72. data/app/components/iron_admin/ui/alert_component.html.haml +2 -2
  73. data/app/components/iron_admin/ui/alert_component.rb +27 -31
  74. data/app/components/iron_admin/ui/badge_component.rb +40 -20
  75. data/app/components/iron_admin/ui/button_component.rb +37 -11
  76. data/app/components/iron_admin/ui/card_component.rb +3 -3
  77. data/app/components/iron_admin/ui/dropdown_component.html.haml +1 -1
  78. data/app/components/iron_admin/ui/dropdown_component.rb +34 -13
  79. data/app/components/iron_admin/ui/empty_state_component.html.haml +4 -5
  80. data/app/components/iron_admin/ui/empty_state_component.rb +2 -2
  81. data/app/components/iron_admin/ui/modal_component.html.haml +5 -5
  82. data/app/components/iron_admin/ui/modal_component.rb +6 -4
  83. data/app/components/iron_admin/ui/pagination_component.html.haml +14 -14
  84. data/app/components/iron_admin/ui/pagination_component.rb +26 -9
  85. data/app/components/iron_admin/ui/scopes_component.html.haml +2 -2
  86. data/app/components/iron_admin/ui/scopes_component.rb +44 -11
  87. data/app/components/iron_admin/ui/tooltip_component.rb +11 -4
  88. data/app/controllers/iron_admin/application_controller.rb +58 -4
  89. data/app/controllers/iron_admin/audit_controller.rb +30 -6
  90. data/app/controllers/iron_admin/concerns/action_executable.rb +37 -0
  91. data/app/controllers/iron_admin/concerns/assignable_references.rb +149 -0
  92. data/app/controllers/iron_admin/concerns/authorizable.rb +11 -0
  93. data/app/controllers/iron_admin/concerns/blank_password_filterable.rb +21 -0
  94. data/app/controllers/iron_admin/concerns/event_emittable.rb +47 -7
  95. data/app/controllers/iron_admin/concerns/filterable.rb +34 -9
  96. data/app/controllers/iron_admin/concerns/nested_permittable.rb +5 -3
  97. data/app/controllers/iron_admin/concerns/nested_tenant_check.rb +159 -0
  98. data/app/controllers/iron_admin/concerns/polymorphic_references.rb +131 -0
  99. data/app/controllers/iron_admin/concerns/scopeable.rb +54 -7
  100. data/app/controllers/iron_admin/concerns/searchable.rb +3 -3
  101. data/app/controllers/iron_admin/concerns/tenant_assignable.rb +118 -0
  102. data/app/controllers/iron_admin/concerns/tenant_containment.rb +146 -0
  103. data/app/controllers/iron_admin/exports_controller.rb +2 -2
  104. data/app/controllers/iron_admin/imports_controller.rb +1 -1
  105. data/app/controllers/iron_admin/resources_controller.rb +48 -41
  106. data/app/controllers/iron_admin/search_controller.rb +1 -2
  107. data/app/controllers/iron_admin/themes_controller.rb +50 -0
  108. data/app/controllers/iron_admin/tools_controller.rb +58 -5
  109. data/app/helpers/iron_admin/action_form_helper.rb +19 -0
  110. data/app/helpers/iron_admin/application_helper.rb +93 -16
  111. data/app/helpers/iron_admin/assignable_records_helper.rb +32 -0
  112. data/app/helpers/iron_admin/component_overrides_helper.rb +9 -4
  113. data/app/helpers/iron_admin/field_display_helper.rb +88 -43
  114. data/app/helpers/iron_admin/related_records_helper.rb +51 -0
  115. data/app/helpers/iron_admin/theme_helper.rb +56 -46
  116. data/app/javascript/iron_admin/controllers/cp_bulk_select_controller.js +12 -0
  117. data/app/javascript/iron_admin/controllers/cp_chart_controller.js +4 -0
  118. data/app/javascript/iron_admin/controllers/cp_disclosure_controller.js +19 -0
  119. data/app/javascript/iron_admin/controllers/cp_search_shortcut_controller.js +39 -0
  120. data/app/javascript/iron_admin/index.js +4 -0
  121. data/app/views/iron_admin/audit/index.html.haml +78 -81
  122. data/app/views/iron_admin/dashboard/index.html.haml +10 -9
  123. data/app/views/iron_admin/form/_action_field.html.haml +50 -0
  124. data/app/views/iron_admin/form/_nested_row.html.haml +18 -13
  125. data/app/views/iron_admin/imports/new.html.haml +14 -13
  126. data/app/views/iron_admin/imports/preview.html.haml +24 -21
  127. data/app/views/iron_admin/resources/_form.html.haml +70 -68
  128. data/app/views/iron_admin/resources/action_form.html.haml +16 -59
  129. data/app/views/iron_admin/resources/bulk_action_form.html.haml +20 -58
  130. data/app/views/iron_admin/resources/edit.html.haml +3 -3
  131. data/app/views/iron_admin/resources/index.html.haml +87 -74
  132. data/app/views/iron_admin/resources/new.html.haml +2 -2
  133. data/app/views/iron_admin/resources/show.html.haml +53 -41
  134. data/app/views/iron_admin/search/index.html.haml +17 -9
  135. data/app/views/iron_admin/shared/_pagination.html.haml +13 -10
  136. data/app/views/iron_admin/shared/error.html.haml +16 -12
  137. data/app/views/iron_admin/tools/action_form.html.haml +9 -55
  138. data/app/views/iron_admin/tools/show.html.haml +4 -5
  139. data/app/views/layouts/iron_admin/_document_head.html.haml +24 -0
  140. data/app/views/layouts/iron_admin/application.html.haml +4 -17
  141. data/app/views/layouts/iron_admin/minimal.html.haml +7 -0
  142. data/config/importmap.rb +2 -0
  143. data/config/locales/en.yml +23 -0
  144. data/config/routes.rb +1 -0
  145. data/docs/FAQ.md +87 -37
  146. data/docs/README.md +8 -2
  147. data/docs/components/README.md +6 -2
  148. data/docs/components/dashboard-components.md +24 -35
  149. data/docs/components/filter-components.md +44 -92
  150. data/docs/components/form-components.md +16 -32
  151. data/docs/components/resource-components.md +46 -27
  152. data/docs/components/ui-components.md +44 -26
  153. data/docs/getting-started/installation.md +5 -1
  154. data/docs/getting-started/quick-start.md +36 -23
  155. data/docs/guides/authentication.md +182 -42
  156. data/docs/guides/components.md +97 -15
  157. data/docs/guides/custom-adapters.md +24 -4
  158. data/docs/guides/dashboard.md +68 -44
  159. data/docs/guides/export.md +24 -8
  160. data/docs/guides/extending.md +206 -51
  161. data/docs/guides/fields.md +229 -70
  162. data/docs/guides/imports.md +33 -18
  163. data/docs/guides/resources.md +333 -111
  164. data/docs/guides/theming.md +930 -58
  165. data/docs/guides/troubleshooting.md +7 -3
  166. data/docs/plugin-system-design.md +8 -7
  167. data/docs/reference/configuration.md +51 -16
  168. data/docs/reference/routes.md +1 -0
  169. data/docs/reference/theme-properties.md +101 -38
  170. data/lib/generators/iron_admin/install/templates/initializer.rb.tt +7 -2
  171. data/lib/generators/iron_admin/install_audit/templates/create_iron_admin_audit_entries.rb.tt +2 -0
  172. data/lib/iron_admin/action_field.rb +11 -0
  173. data/lib/iron_admin/adapters/active_record.rb +95 -0
  174. data/lib/iron_admin/adapters/base.rb +107 -0
  175. data/lib/iron_admin/adapters/http/query.rb +21 -0
  176. data/lib/iron_admin/adapters/http.rb +84 -4
  177. data/lib/iron_admin/adapters/mongoid.rb +96 -2
  178. data/lib/iron_admin/audit_log.rb +64 -6
  179. data/lib/iron_admin/authentication_warning.rb +31 -0
  180. data/lib/iron_admin/concerns/filter_definable.rb +15 -1
  181. data/lib/iron_admin/concerns/nestable.rb +25 -0
  182. data/lib/iron_admin/concerns/scope_countable.rb +56 -0
  183. data/lib/iron_admin/concerns/soft_deletable.rb +28 -9
  184. data/lib/iron_admin/configuration/components.rb +14 -3
  185. data/lib/iron_admin/configuration/theme/neutral_defaults.rb +179 -0
  186. data/lib/iron_admin/configuration/theme.rb +292 -87
  187. data/lib/iron_admin/configuration.rb +340 -45
  188. data/lib/iron_admin/dashboard.rb +22 -38
  189. data/lib/iron_admin/engine.rb +16 -2
  190. data/lib/iron_admin/errors.rb +3 -0
  191. data/lib/iron_admin/field.rb +78 -17
  192. data/lib/iron_admin/field_inferrer.rb +61 -3
  193. data/lib/iron_admin/field_override_warning.rb +67 -0
  194. data/lib/iron_admin/import/import_preview.rb +56 -7
  195. data/lib/iron_admin/import/importer.rb +91 -14
  196. data/lib/iron_admin/import/tenant_precheck.rb +67 -0
  197. data/lib/iron_admin/plugin/registration.rb +64 -0
  198. data/lib/iron_admin/plugin_registry.rb +3 -2
  199. data/lib/iron_admin/policy.rb +22 -12
  200. data/lib/iron_admin/policy_coverage_warning.rb +46 -0
  201. data/lib/iron_admin/request_context.rb +18 -0
  202. data/lib/iron_admin/resource.rb +218 -77
  203. data/lib/iron_admin/resource_registry.rb +86 -13
  204. data/lib/iron_admin/scope_counts.rb +73 -0
  205. data/lib/iron_admin/tenant_scope.rb +30 -0
  206. data/lib/iron_admin/tool.rb +61 -12
  207. data/lib/iron_admin/tool_context.rb +10 -6
  208. data/lib/iron_admin/version.rb +1 -1
  209. data/lib/iron_admin.rb +29 -2
  210. metadata +37 -7
@@ -154,7 +154,7 @@ appear if the deferred retry *also* fails.
154
154
 
155
155
  **Cause:** Authentication block redirecting or returning false.
156
156
 
157
- **Solution:** Check `config/initializers/iron_admin.rb`:
157
+ **Solution:** Check `config/initializers/iron_admin.rb`. Check the block's value: only an exact `false` denies the request. End a status `false` (a failed `save` or `update`, a failed `Rails.cache.write`, or an assignment such as `Current.impersonating = false`) with `nil`. See [UPGRADING.md, section 9](../../UPGRADING.md#9-an-authenticate-block-whose-value-is-false-now-denies-access).
158
158
  ```ruby
159
159
  config.authenticate do |controller|
160
160
  # Ensure this doesn't redirect for authenticated users
@@ -250,8 +250,12 @@ The proc receives the current user, not the record.
250
250
 
251
251
  **Solution:** Add explicit preloading:
252
252
  ```ruby
253
- class OrderResource < IronAdmin::Resource
254
- preload :customer, :line_items, :shipping_address
253
+ module IronAdmin
254
+ module Resources
255
+ class OrderResource < IronAdmin::Resource
256
+ preload :customer, :line_items, :shipping_address
257
+ end
258
+ end
255
259
  end
256
260
  ```
257
261
 
@@ -1,8 +1,8 @@
1
1
  # Plugin / Community Extension System — Design Proposal
2
2
 
3
3
  > Status: **Design proposal + proof-of-concept skeleton.** The registration
4
- > core and three extension points (menu items, component overrides and field
5
- > types) are implemented and tested; the remaining extension points are
4
+ > core and four extension points (menu items, component overrides, field
5
+ > types and themes) are implemented and tested; the remaining extension points are
6
6
  > specified here but not yet built. This
7
7
  > document is the contract a maintainer should approve before the feature is
8
8
  > completed.
@@ -32,7 +32,7 @@ of admin functionality that *many* host apps install with a single line.
32
32
  - A normal Rails gem that `require`s IronAdmin and calls a small, stable
33
33
  registration API.
34
34
  - A bundle of one or more extensions: resources, dashboards, tools, field
35
- types, adapters, component overrides, and custom menu entries.
35
+ types, themes, adapters, component overrides, and custom menu entries.
36
36
  - Versioned and declared-compatible against an IronAdmin version range.
37
37
  - Activated **explicitly** by the host (`IronAdmin.register_plugin`) — the host
38
38
  keeps an auditable list of everything extending its admin panel.
@@ -65,6 +65,7 @@ builds on, and its status in this proposal.
65
65
  | Menu items | *(new)* — sidebar was resource/tool-derived only | **Implemented** |
66
66
  | Component override | `config.components.<slot> = Klass` | **Implemented** |
67
67
  | Field types | `FieldTypeRegistry.register` / `register_field_type`| **Implemented** |
68
+ | Themes | `admin.theme` → `Configuration#register_plugin_theme`, plus the ownership map | **Implemented** |
68
69
  | Resources | `inherited` → `ResourceRegistry`, Zeitwerk `push_dir`| Design only |
69
70
  | Dashboards | `inherited` → `IronAdmin.dashboard_class` | Design only |
70
71
  | Tools | `inherited` → `ToolRegistry` | Design only |
@@ -107,7 +108,7 @@ anywhere" model the PoC uses for the config-level extension points. See §5.
107
108
  ### 2b. Component overrides — **implemented**
108
109
 
109
110
  Same as setting `config.components.<slot>`. Any global slot (`:shell`,
110
- `:navbar`, `:sidebar`, `:table`, `:form`, `:filter_bar`, `:search`) can be
111
+ `:navbar`, `:sidebar`, `:flash`, `:table`, `:form`, `:filter_bar`, `:search`) can be
111
112
  swapped, and the override is used when IronAdmin renders that slot. A
112
113
  resource's own `component` override still wins for `:table`, `:form`,
113
114
  `:filter_bar` and `:search`:
@@ -293,8 +294,8 @@ Recommended posture:
293
294
 
294
295
  - **Trust before install.** Document that plugins are not sandboxed. Encourage
295
296
  hosts to vet plugin source and pin exact versions.
296
- - **Explicit activation** (§4) is the mitigation that exists: nothing runs
297
- until the host names it.
297
+ - **Explicit activation** (§4) only controls what is wired into IronAdmin.
298
+ Requiring a plugin gem already runs its Ruby.
298
299
  - **Fail-safe activation.** Consider (future) wrapping each plugin's `activate!`
299
300
  so one broken plugin logs and is skipped rather than taking down boot —
300
301
  mirroring how `ResourceRegistry.finalize!` already isolates per-resource
@@ -359,7 +360,7 @@ under a "Billing" group in the sidebar. If Acme later upgrades to IronAdmin
359
360
  - `IronAdmin::Plugin` base class (metadata DSL, `setup`, compatibility check,
360
361
  `activate!`).
361
362
  - `IronAdmin::Plugin::Registration` facade with `menu_item`, `component`,
362
- `field_type`.
363
+ `field_type`, `theme`.
363
364
  - `IronAdmin::PluginRegistry` (idempotent register/activate, `activate_all!`).
364
365
  - `IronAdmin.register_plugin` host entry point.
365
366
  - `IronAdmin::MenuItem` + `IronAdmin::MenuRegistry` (new sidebar extension
@@ -7,28 +7,21 @@ IronAdmin.configure do |config|
7
7
  # --- General ---
8
8
  config.title = "Admin"
9
9
  config.logo = nil
10
+ config.favicon = nil # e.g. "/icon.svg"
10
11
  config.per_page = 25
11
12
  config.default_sort = :created_at
12
13
  config.default_sort_direction = :desc
14
+ config.scope_counts = false # true: each scope tab shows how many records it would list
15
+ config.strict_tool_actions = false # true: only tool_action names dispatch
16
+ config.default_policy = :allow # :deny: resources without a policy and tools without tool_access answer 403
13
17
 
14
18
  # --- Multi-Tenant Support ---
15
19
  config.tenant_scope do |scope|
16
20
  scope.where(organization_id: Current.organization.id)
17
21
  end
18
22
 
19
- # --- Badge Colors ---
20
- config.badge_colors = {
21
- green: "bg-green-100 text-green-800",
22
- red: "bg-red-100 text-red-800",
23
- yellow: "bg-yellow-100 text-yellow-800",
24
- blue: "bg-blue-100 text-blue-800",
25
- indigo: "bg-indigo-100 text-indigo-800",
26
- purple: "bg-purple-100 text-purple-800",
27
- pink: "bg-pink-100 text-pink-800",
28
- orange: "bg-orange-100 text-orange-800",
29
- teal: "bg-teal-100 text-teal-800",
30
- gray: "bg-gray-100 text-gray-800"
31
- }
23
+ # --- Badge Colors (status value => color name; add entries, don't replace the Hash) ---
24
+ config.badge_colors["on_hold"] = "orange"
32
25
 
33
26
  # --- Authentication ---
34
27
  config.authenticate do |controller|
@@ -40,12 +33,21 @@ IronAdmin.configure do |config|
40
33
  # --- Audit Logging ---
41
34
  config.audit_enabled = true
42
35
  config.audit_storage = :memory # or :database
36
+ config.audit_user_labels { |identifiers| User.where(id: identifiers).pluck(:id, :email).to_h }
43
37
 
44
38
  config.on_action do |event|
45
39
  end
46
40
 
47
- # --- Theme ---
48
- config.theme do |t|
41
+ # --- Themes ---
42
+ config.theme do |t| # the default theme (Neutral unless default_theme names another)
43
+ t.link = "text-indigo-600 hover:text-indigo-700"
44
+ end
45
+ config.register_theme(:midnight, label: "Midnight") do |t|
46
+ t.color_scheme = "dark"
47
+ end
48
+ config.default_theme = :neutral
49
+ config.theme_resolver do |request| # default: the theme switcher's cookie
50
+ request.cookies[IronAdmin::Configuration::THEME_COOKIE]
49
51
  end
50
52
 
51
53
  # --- Components (a ViewComponent class or its class name; nil = built-in) ---
@@ -56,6 +58,8 @@ IronAdmin.configure do |config|
56
58
  config.components.navbar = nil
57
59
  config.components.sidebar = nil
58
60
  config.components.shell = nil
61
+ config.components.flash = nil
62
+ config.components.theme_switcher = nil
59
63
  config.components.fields[:type] = nil
60
64
  end
61
65
  ```
@@ -68,9 +72,13 @@ end
68
72
  |--------|------|---------|-------------|
69
73
  | `title` | String | `"Admin"` | Title shown in navbar |
70
74
  | `logo` | String | `nil` | Path to logo image |
75
+ | `favicon` | String | `nil` | Icon linked from every admin page with `<link rel="icon">`: a path (`"/icon.svg"`), a URL or an asset name, resolved like `logo`. With `nil`, the admin layout links no icon and browsers request `/favicon.ico` |
71
76
  | `per_page` | Integer | `25` | Records per page |
77
+ | `scope_counts` | Boolean | `false` | When `true`, each scope tab shows how many records that tab would list. Each counted scope runs one query. A resource overrides this with `scope_counts`. See [Scopes](../guides/resources.md#scopes) |
72
78
  | `default_sort` | Symbol | `:created_at` | Default sort column |
73
79
  | `default_sort_direction` | Symbol | `:desc` | Default sort direction (`:asc` or `:desc`) |
80
+ | `default_policy` | Symbol | `:allow` | What a resource without a `policy` block, and a tool without `tool_access`, allows. `:allow` allows every action; `:deny` denies them all. Any other value raises `ArgumentError`. See [Policies](../guides/authentication.md#policies) |
81
+ | `strict_tool_actions` | Boolean | `false` | When `true`, tools dispatch only actions declared with `tool_action`. Undeclared names return 404, including the legacy bare-method fallback. See [Custom Tools](../guides/extending.md#custom-tools) |
74
82
 
75
83
  ### Multi-Tenant Support
76
84
 
@@ -94,6 +102,7 @@ The tenant scope is applied to:
94
102
  |--------|------|---------|-------------|
95
103
  | `audit_enabled` | Boolean | `false` | Enable built-in audit logging |
96
104
  | `audit_storage` | Symbol | `:memory` | Storage backend (`:memory` or `:database`) |
105
+ | `audit_user_labels` | Block | `nil` | Labels the audit log's users: receives the user identifiers on the page, returns `{ identifier => label }`. See [User Labels](../guides/authentication.md#user-labels) |
97
106
 
98
107
  When `audit_storage: :database`, run the migration:
99
108
 
@@ -106,14 +115,38 @@ View audit logs at `/admin/audit`.
106
115
 
107
116
  For custom audit logging, use the `on_action` callback instead.
108
117
 
118
+ ### Themes
119
+
120
+ | Option | Type | Default | Description |
121
+ |--------|------|---------|-------------|
122
+ | `theme` | Block | Neutral | Yields and returns the default theme, to change its properties |
123
+ | `register_theme(name, label:)` | Method with a block | none | Registers a named theme that starts from the Neutral values. A Symbol, a String and any other case are the same name. A name a plugin owns raises `PluginError`. With two or more themes, the navbar shows a theme switcher |
124
+ | `default_theme` | Symbol | `:neutral` | The theme used when a request resolves no registered theme |
125
+ | `theme_resolver` | Block | reads the `iron_admin_theme` cookie | Receives the request and returns the name of its theme. Unknown names and errors fall back to `default_theme` |
126
+
127
+ Read the request's theme with `IronAdmin.current_theme`. See the
128
+ [Theming guide](../guides/theming.md) and the [Theme reference](theme-properties.md).
129
+
109
130
  ### Badge Colors
110
131
 
111
- Default color palette for badge fields. Add custom colors:
132
+ `badge_colors` maps status values to badge color names, such as `"active" => "green"` (see
133
+ [Badge Colors](../guides/fields.md#badge-colors) for the defaults). Add or change entries;
134
+ assigning a new Hash replaces the default mapping:
135
+
136
+ ```ruby
137
+ config.badge_colors["on_hold"] = "orange"
138
+ ```
139
+
140
+ The classes of each color come from the theme's `badge_palette`. An entry that maps a color
141
+ name Symbol to classes sets that color's classes in every theme, and those badges have no dot:
112
142
 
113
143
  ```ruby
114
144
  config.badge_colors[:cyan] = "bg-cyan-100 text-cyan-800"
115
145
  ```
116
146
 
147
+ To add a color that follows the theme, add it to the theme's `badge_palette` and
148
+ `badge_dot_palette` instead (see [Badges, alerts and chips](../guides/theming.md#badges-alerts-and-chips)).
149
+
117
150
  ### Components
118
151
 
119
152
  Override global components. Each value is a `ViewComponent::Base` subclass or its class name
@@ -130,6 +163,8 @@ slot passes.
130
163
  | `search` | Search box on index pages |
131
164
  | `navbar` | Top bar inside the built-in shell |
132
165
  | `sidebar` | Navigation inside the built-in shell |
166
+ | `flash` | Flash messages above the page content inside the built-in shell |
167
+ | `theme_switcher` | Theme switcher in the built-in navbar, rendered when two or more themes are registered |
133
168
  | `shell` | Shell around every admin page |
134
169
  | `fields[:type]` | Form input for every field of that type (form only; display is unchanged) |
135
170
 
@@ -8,6 +8,7 @@ Mount: `mount IronAdmin::Engine => "/admin"`
8
8
  |--------|------|--------|-------------|
9
9
  | GET | `/admin` | `dashboard#index` | Dashboard |
10
10
  | GET | `/admin/search?q=...` | `search#index` | Global search |
11
+ | POST | `/admin/theme` | `themes#update` | Theme switcher: stores the `theme` param in the theme cookie and redirects to `return_to` |
11
12
  | GET | `/admin/:resource/export` | `exports#show` | Export |
12
13
  | GET | `/admin/:resource/import` | `imports#new` | Import upload form |
13
14
  | POST | `/admin/:resource/import/preview` | `imports#preview` | Import preview |
@@ -1,38 +1,101 @@
1
- # Theme Properties Reference
2
-
3
- | Category | Property | Default |
4
- |----------|----------|---------|
5
- | Buttons | `btn_primary` | `bg-indigo-600 text-white hover:bg-indigo-700 focus:ring-2 focus:ring-indigo-500/20 focus:ring-offset-1` |
6
- | | `btn_secondary` | `bg-white text-gray-700 border border-gray-300 hover:bg-gray-50 hover:border-gray-400` |
7
- | | `btn_danger` | `bg-red-600 text-white hover:bg-red-700` |
8
- | | `btn_ghost` | `bg-gray-100 text-gray-700 hover:bg-gray-200` |
9
- | Links | `link` | `text-indigo-600 hover:text-indigo-900` |
10
- | | `link_muted` | `text-gray-500 hover:text-gray-700` |
11
- | Focus | `focus_ring` | `focus:border-indigo-500 focus:ring-2 focus:ring-indigo-500/20` |
12
- | Inputs | `input_border` | `border-gray-300 hover:border-gray-400` |
13
- | | `input_focus` | `focus:border-indigo-500 focus:ring-2 focus:ring-indigo-500/20` |
14
- | Checkbox | `checkbox_checked` | `checked:border-indigo-600 checked:bg-indigo-600 focus:ring-2 focus:ring-indigo-500/20` |
15
- | Scopes | `scope_active` | `border-indigo-600 text-indigo-600` |
16
- | | `scope_inactive` | `border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300` |
17
- | Badge | `badge_count` | `bg-indigo-600 text-white` |
18
- | Sidebar | `sidebar_bg` | `bg-gray-900` |
19
- | | `sidebar_title` | `text-white` |
20
- | | `sidebar_link` | `text-gray-300` |
21
- | | `sidebar_link_hover` | `hover:bg-gray-800 hover:text-white` |
22
- | | `sidebar_group_label` | `text-gray-400` |
23
- | Navbar | `navbar_bg` | `bg-white` |
24
- | | `navbar_border` | `border-gray-200` |
25
- | | `navbar_search_bg` | `bg-gray-50` |
26
- | | `navbar_search_focus_bg` | `focus:bg-white` |
27
- | Table | `table_header_bg` | `bg-gray-50` |
28
- | | `table_row_hover` | `hover:bg-gray-50` |
29
- | | `table_border` | `divide-gray-200` |
30
- | Cards | `card_bg` | `bg-white` |
31
- | | `card_border` | `border-gray-200` |
32
- | | `card_shadow` | `shadow` |
33
- | Typography | `font_family` | `""` |
34
- | | `heading_weight` | `font-bold` |
35
- | | `body_text` | `text-gray-900` |
36
- | | `muted_text` | `text-gray-500` |
37
- | | `label_text` | `text-gray-700` |
38
- | Layout | `border_radius` | `rounded-lg` |
1
+ # Theme Reference
2
+
3
+ The methods, constants and helpers of the theme system. The [Theming guide](../guides/theming.md)
4
+ explains how to use them, and its [Theme properties](../guides/theming.md#theme-properties)
5
+ tables list every property with its Neutral value and what it controls.
6
+
7
+ ## Properties
8
+
9
+ A theme has 96 properties, each with a reader and a writer (`theme.card_bg`,
10
+ `theme.card_bg = "bg-white"`). They hold Tailwind classes, except `font_stylesheet_url` (a URL
11
+ or `nil`), `color_scheme` (`"light"` or `"dark"`), the chart properties (CSS colors, a Chart.js point
12
+ style and a width in pixels) and the palettes (Hashes).
13
+
14
+ | Group | Properties |
15
+ |-------|------------|
16
+ | Buttons and links | `btn_primary`, `btn_secondary`, `btn_danger`, `btn_ghost`, `link`, `link_muted` |
17
+ | Forms and controls | `focus_ring`, `input_border`, `input_focus`, `input_error`, `placeholder_text`, `checkbox_checked`, `checkbox_border`, `checkbox_radius`, `control_radius`, `control_shadow`, `disabled_text`, `rich_text_editor`, `rich_text_toolbar` |
18
+ | Scope tabs and counts | `scope_active`, `scope_inactive`, `badge_count` |
19
+ | Sidebar | `sidebar_bg`, `sidebar_border`, `sidebar_title`, `sidebar_link`, `sidebar_link_hover`, `sidebar_link_active`, `sidebar_group_label` |
20
+ | Navbar | `navbar_bg`, `navbar_border`, `navbar_border_width`, `navbar_search_bg`, `navbar_search_focus_bg`, `navbar_text`, `kbd`, `skip_link` |
21
+ | Tables | `table_header_bg`, `table_header_text`, `table_cell_padding`, `table_frame`, `table_sticky_shadow`, `table_row_hover`, `table_sticky_row_hover`, `table_border`, `table_head_border` |
22
+ | Cards and panels | `card_bg`, `card_border`, `card_shadow`, `popover_shadow`, `popover_bg`, `card_title` |
23
+ | Typography | `font_family`, `font_stylesheet_url`, `heading_font`, `heading_weight`, `page_title`, `label_transform`, `field_label_transform`, `body_text`, `muted_text`, `label_text`, `error_text`, `success_text` |
24
+ | Layout and surfaces | `main_bg`, `border_radius`, `border_width`, `color_scheme`, `swatch`, `surface_muted`, `item_hover`, `item_active`, `icon_muted`, `overlay_bg` |
25
+ | Feedback | `alert_palette`, `alert_shadow`, `badge_palette`, `badge_dot_palette`, `badge_shape`, `chip`, `danger_item`, `tooltip`, `code_block`, `code_font`, `progress_track`, `pagination_active` |
26
+ | Dashboard | `metric_label`, `metric_value`, `metric_icon` |
27
+ | Charts | `chart_colors`, `chart_border_color`, `chart_grid_color`, `chart_text_color`, `chart_point_style`, `chart_slice_border_color`, `chart_border_width` |
28
+
29
+ ## `IronAdmin::Configuration::Theme`
30
+
31
+ | Method | Returns |
32
+ |--------|---------|
33
+ | `Theme.new(name: :neutral, label: nil)` | A theme with the Neutral values. `label` defaults to the titleized name |
34
+ | `#name` | The Symbol the theme is registered under, which is also the value its cookie stores |
35
+ | `#label` | The String the theme switcher shows |
36
+ | `#dark?` | Whether `color_scheme` is `"dark"` |
37
+ | `#popover_background` | `popover_bg`, or `card_bg` while `popover_bg` is empty: the background of floating surfaces |
38
+ | `#table_head_divider` | `table_head_border`, or `table_border` while `table_head_border` is empty: the line under a table's header row |
39
+ | `#scheme_class` | `"scheme-dark"` for a dark theme, else `"scheme-light"` (`Theme::SCHEME_CLASSES`) |
40
+ | `#dup` | A copy whose Arrays and Hashes (`chart_colors`, the palettes) are copies too |
41
+
42
+ ## Configuration
43
+
44
+ | Method | Description |
45
+ |--------|-------------|
46
+ | `config.theme { \|t\| ... }` | Yields and returns the default theme: the one `default_theme` names, else Neutral. `config.theme_config` returns the same theme |
47
+ | `config.register_theme(name, label: name.to_s.titleize) { \|t\| ... }` | Builds a theme with the pristine Neutral values, yields it, stores it under the normalized name and returns it. A Symbol, a String and any other case are the same name (`:Harbor` and `"harbor"`). Registering a name the app owns replaces the theme. A name a plugin owns raises `PluginError`. The theme and its owner are stored only after the block returns. Raises `ArgumentError` for a blank name |
48
+ | `config.themes` | `Hash{Symbol => Theme}` of the registered themes, the default theme first, then the others in registration order |
49
+ | `config.default_theme` / `config.default_theme = name` | The name of the theme used when a request resolves none (default `:neutral`). The writer raises `ArgumentError` for a blank name |
50
+ | `config.theme_resolver { \|request\| ... }` | Sets the block that returns the name (String, Symbol or `nil`) of each request's theme, and returns the resolver. Without a block, it returns the current resolver |
51
+ | `config.resolve_theme(request)` | The theme the resolver names; the default theme for an unknown, blank or `nil` name, or when the resolver raises (logged as a warning) |
52
+ | `config.theme_for(name)` | The theme registered under `name`, else the default theme |
53
+ | `config.find_theme(name)` | The theme registered under `name` (a String, a Symbol or another case), else `nil`. A String that is not valid UTF-8 is `nil` |
54
+
55
+ | Constant | Value |
56
+ |----------|-------|
57
+ | `IronAdmin::Configuration::NEUTRAL_THEME` | `:neutral`, the name of the built-in theme |
58
+ | `IronAdmin::Configuration::THEME_COOKIE` | `"iron_admin_theme"`, the cookie the switcher sets |
59
+ | `IronAdmin::Configuration::DEFAULT_THEME_RESOLVER` | The resolver used until `theme_resolver` gets a block: it reads `THEME_COOKIE` |
60
+
61
+ ## The theme of a request
62
+
63
+ | API | Description |
64
+ |-----|-------------|
65
+ | `IronAdmin.current_theme` | The theme of the current request, or the default theme outside a request. Read it in your own components |
66
+ | `IronAdmin::RequestContext.theme` | Where `IronAdmin::ApplicationController` stores the resolved theme, before authentication (`IronAdmin::RequestContext` is an `ActiveSupport::CurrentAttributes`) |
67
+ | `IronAdmin.configuration.theme` | The default theme, whatever the request. Use it to configure the theme, not to render |
68
+
69
+ ## Helpers and class recipes
70
+
71
+ `IronAdmin::ThemeHelper`, available in the engine's views and in views you override:
72
+
73
+ | Helper | Returns |
74
+ |--------|---------|
75
+ | `t` | `IronAdmin.current_theme` |
76
+ | `cp_btn_primary`, `cp_btn_secondary`, `cp_btn_danger`, `cp_btn_ghost` | A complete 36px button (`cp_btn_primary_lg` and `cp_btn_filter_apply` are the same as `cp_btn_primary`) |
77
+ | `cp_input_class(error: false, padding: "px-3")`, `cp_select_class(error: false)`, `cp_textarea_class(error: false)`, `cp_file_input_class(error: false)` | A complete control; `error: true` uses `input_error` |
78
+ | `cp_checkbox_class`, `cp_radio_class` | A checkbox or radio button with the engine's check mark or dot |
79
+ | `cp_filter_input_class`, `cp_search_class`, `cp_navbar_search_class` | Filter, search and navbar search inputs |
80
+ | `cp_card` | `card_bg`, `border_width`, `card_border`, `border_radius` and `card_shadow` |
81
+ | `cp_heading` | `heading_weight` with `heading_font`, else `font_family` |
82
+ | `cp_badge_count` | A count bubble with `badge_shape` and `badge_count` |
83
+ | `cp_link`, `cp_link_muted`, `cp_focus`, `cp_scope_active`, `cp_scope_inactive`, `cp_sidebar_bg`, `cp_sidebar_title`, `cp_sidebar_link`, `cp_sidebar_link_active`, `cp_sidebar_group_label`, `cp_body_text`, `cp_muted_text`, `cp_label_text`, `cp_table_header_bg`, `cp_table_row_hover`, `cp_table_border` | The matching property (`cp_focus` is `input_focus`; `cp_sidebar_link` is `sidebar_link` with `sidebar_link_hover`) |
84
+ | `cp_google_fonts?` | Whether `font_stylesheet_url` is on `fonts.googleapis.com` |
85
+
86
+ `IronAdmin::Form::ControlClasses` builds the controls from a theme, for components of your own:
87
+ `button(theme, variant = :primary)` (`:primary`, `:secondary`, `:danger`, `:ghost`; another
88
+ variant raises `ArgumentError`), `input(theme, error: false, muted: false, padding: "px-3")`,
89
+ `textarea(theme, error: false, muted: false)`, `select(theme, error: false, muted: false)`,
90
+ `file_input(theme, error: false)`, `checkbox(theme)` and `radio(theme)`. `muted: true` is a
91
+ readonly or disabled control (`surface_muted`).
92
+
93
+ ## Theme switcher
94
+
95
+ | Part | Description |
96
+ |------|-------------|
97
+ | `IronAdmin::Layout::ThemeSwitcherComponent` | The navbar disclosure. It renders only with two or more themes |
98
+ | `theme_switcher` component slot | Replaces it. Keywords: `themes` (Array, default first), `current_theme`, `current_user` |
99
+ | `POST /admin/theme` (`themes#update`, `iron_admin.theme_path`) | Params `theme` and `return_to`. Stores a registered theme in `THEME_COOKIE` and redirects with `303` |
100
+ | `cp-disclosure` Stimulus controller | Closes the disclosure on Escape and on outside clicks |
101
+ | `iron_admin.theme_switcher.button_label`, `.menu_label`, `.unknown` | Its translations |
@@ -1,8 +1,13 @@
1
1
  IronAdmin.configure do |config|
2
2
  config.title = "<%= Rails.application.class.module_parent_name %> Admin"
3
3
 
4
- config.authenticate do |controller|
5
- # controller.redirect_to "/login" unless controller.session[:user_id]
4
+ # Every request is denied (403) until you replace this block with your
5
+ # app's authentication: return false to deny, redirect to your sign-in
6
+ # page, or return anything else to allow. Recipes for Devise and the
7
+ # Rails 8 authentication generator:
8
+ # https://github.com/rubylab-app/iron_admin/blob/main/docs/guides/authentication.md
9
+ config.authenticate do |_controller|
10
+ false
6
11
  end
7
12
 
8
13
  config.current_user do |controller|
@@ -9,11 +9,13 @@ class CreateIronAdminAuditEntries < ActiveRecord::Migration[<%= ActiveRecord::Mi
9
9
  t.integer :record_id
10
10
  t.text :record_changes
11
11
  t.string :ip_address
12
+ t.string :tenant_key
12
13
  t.timestamps
13
14
  end
14
15
 
15
16
  add_index :iron_admin_audit_entries, :resource
16
17
  add_index :iron_admin_audit_entries, :action
17
18
  add_index :iron_admin_audit_entries, :created_at
19
+ add_index :iron_admin_audit_entries, :tenant_key
18
20
  end
19
21
  end
@@ -52,5 +52,16 @@ module IronAdmin
52
52
  @placeholder = placeholder
53
53
  @options = options
54
54
  end
55
+
56
+ # A required :boolean must be checked: "0", "false" and "off" count as missing.
57
+ #
58
+ # @param value [Object, nil] The submitted value
59
+ # @return [Boolean] Whether the field is required and the value is blank, so the action must not run
60
+ def missing?(value)
61
+ return false if required.blank?
62
+ return true if value.blank?
63
+
64
+ type == :boolean && !ActiveModel::Type::Boolean.new.cast(value)
65
+ end
55
66
  end
56
67
  end
@@ -106,6 +106,17 @@ module IronAdmin
106
106
  scope.count
107
107
  end
108
108
 
109
+ # Rows the relation lists. +count(:all)+ ignores a select list, and a
110
+ # grouped count (a Hash of group key to count) becomes the number of
111
+ # groups. That is the total the index pagination shows.
112
+ #
113
+ # @param scope [ActiveRecord::Relation, nil]
114
+ # @return [Integer]
115
+ def exact_count(scope = nil)
116
+ result = (scope || all).count(:all)
117
+ result.is_a?(Hash) ? result.size : result
118
+ end
119
+
109
120
  # --- Search ---
110
121
 
111
122
  def search_column(scope, column, query)
@@ -126,6 +137,41 @@ module IronAdmin
126
137
  model_class.new(attrs)
127
138
  end
128
139
 
140
+ # Plain scalar equalities on +scope+ that belong to the scope's model.
141
+ #
142
+ # Reads +where_values_hash+ and keeps keys that are attributes of
143
+ # +scope.klass+ when the scope exposes it, otherwise this adapter's
144
+ # model. Arrays, ranges, hashes, sets, and relations are omitted: an
145
+ # +IN+ list must not be written onto a scalar column.
146
+ #
147
+ # @param scope [ActiveRecord::Relation]
148
+ # @return [Hash{String => Object}]
149
+ def scope_attributes(scope)
150
+ values = scope_where_values(scope)
151
+ return {} unless values
152
+
153
+ allowed = scope_attribute_names(scope)
154
+ values.each_with_object({}) do |(key, value), kept|
155
+ name = key.to_s
156
+ next unless allowed.include?(name)
157
+ next if non_scalar_scope_value?(value)
158
+
159
+ kept[name] = value
160
+ end
161
+ end
162
+
163
+ # Builds a record from +scope+ so equality conditions become attributes.
164
+ #
165
+ # Submitted +attrs+ are applied first. {#scope_attributes} is assigned
166
+ # afterwards, so a posted tenant id cannot move the row to another tenant.
167
+ #
168
+ # @param scope [ActiveRecord::Relation] Scope to build from
169
+ # @param attrs [Hash, ActionController::Parameters] Initial attributes
170
+ # @return [ActiveRecord::Base] New record
171
+ def build_in(scope, attrs = {})
172
+ build(attrs).tap { |record| record.assign_attributes(scope_attributes(scope)) }
173
+ end
174
+
129
175
  def save(record)
130
176
  record.save
131
177
  end
@@ -144,12 +190,43 @@ module IronAdmin
144
190
  scope.unscope(where: column.to_sym)
145
191
  end
146
192
 
193
+ # @return [Boolean]
194
+ def supports_soft_delete_tabs?
195
+ true
196
+ end
197
+
198
+ # The scope without the column's condition, keeping only rows whose column is not nil.
199
+ # @param scope [Object] The current query scope
200
+ # @param column [Symbol, String] Soft-delete column
201
+ # @return [Object]
202
+ def only_soft_deleted(scope, column)
203
+ unscope_column(scope, column).where.not(column.to_sym => nil)
204
+ end
205
+
147
206
  # --- Transactions ---
148
207
 
208
+ # Active Record can roll a tenant miss back inside {#transaction}.
209
+ #
210
+ # The in-memory check stays unused: {#scope_match} keeps the base
211
+ # +:unknown+, so a caller that skipped the transactional path fails closed.
212
+ #
213
+ # @return [Boolean]
214
+ def supports_transactions?
215
+ true
216
+ end
217
+
149
218
  def transaction(&)
150
219
  ::ActiveRecord::Base.transaction(&)
151
220
  end
152
221
 
222
+ # Runs the block in a nested transaction that can roll back on its own.
223
+ #
224
+ # @yield The block to run inside the savepoint
225
+ # @return [Object] the block's return value
226
+ def savepoint(&)
227
+ ::ActiveRecord::Base.transaction(requires_new: true, &)
228
+ end
229
+
153
230
  # Waits for every open transaction to commit, or runs the block at once
154
231
  # when none is open.
155
232
  def after_commit(&)
@@ -245,6 +322,24 @@ module IronAdmin
245
322
  end
246
323
  end
247
324
  end
325
+
326
+ def scope_where_values(scope)
327
+ return unless scope.respond_to?(:where_values_hash)
328
+
329
+ scope.where_values_hash
330
+ end
331
+
332
+ # Attribute names a scope may copy: +scope.klass+ when it responds,
333
+ # otherwise the adapter model.
334
+ def scope_attribute_names(scope)
335
+ model = scope.respond_to?(:klass) ? scope.klass : model_class
336
+ model.attribute_names.map(&:to_s)
337
+ end
338
+
339
+ def non_scalar_scope_value?(value)
340
+ value.is_a?(Array) || value.is_a?(Range) || value.is_a?(Hash) ||
341
+ (defined?(::Set) && value.is_a?(::Set)) || value.is_a?(::ActiveRecord::Relation)
342
+ end
248
343
  end
249
344
  end
250
345
  end