rails_admin_next 1.1.2 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bdbd212982bdb74e9a2288a5c14eba746b74b0a0ed902afbb0671cbdfd5c107
-  data.tar.gz: 119040f95b74f79a05571d9f099cb98668efa5921ee2a4b43668b3fb320302ec
+  metadata.gz: 957743cf70d6fa24bb0cb1eaf74ca15b4a3b2996e0dca4f5dcee2d6428985d6b
+  data.tar.gz: a205770a7170c2b1ce7e04a85cd6422f6cda1d150da237df81795387af8cc18d
 SHA512:
-  metadata.gz: 583c910d3d95569fb8031b30bfda1a71ae61ecc090bdd0e8289d9e0d4ea01ee7cf635e417c912d17a2a22c5d9f1bfe764d057391fb58744c21c1c22099130531
-  data.tar.gz: f7c7784f080f80977c21d9ae3bc02a822a1b2576aafe07f0dc063c4c7702180f425ea7905f00d8171e0a889a8842311cbff67ffd8268601eee68659b8bfdd032
+  metadata.gz: ad848e8080f75c1e3d6b12c180dcb745bb4a3caea7791ee08d4fec1d97567836effacf01ea340a764b0febb4a52c345e793b3d1708d7496e9d1c2e3f6a167f6d
+  data.tar.gz: 37ec4a516104eb2ecc4d8924c758ad862b8fa091f32a0d460b0dfda2f8bc566a233fa61ea81d6cdbbfe49695b1d71eb0aed55f75c281001e9d86a73821fbe8a8

data/Gemfile

@@ -19,6 +19,10 @@ group :test do
   gem "generator_spec"
   gem "image_processing"
   gem "pundit"
+  # Pinned within 0.10: Gemfile.lock is not committed here, so CI resolves fresh on every run
+  # and no Dependabot PR stages a release first, and the discovery spec drives Hyperdrive's
+  # pre-1.0 discovery API, which has renamed keys within 0.x before.
+  gem "rails-hyperdrive", "~> 0.10.1", require: false
   gem "rspec-rails"
   gem "rspec-retry"
   gem "ruby-vips"

data/README.md

@@ -8,7 +8,7 @@
 
 [![Build](https://github.com/6temes/rails_admin_next/actions/workflows/test.yml/badge.svg)](https://github.com/6temes/rails_admin_next/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
-[![Ruby](https://img.shields.io/badge/Ruby-4.0.5%2B-CC342D.svg)](https://www.ruby-lang.org)
+[![Ruby](https://img.shields.io/badge/Ruby-4.0.9%2B-CC342D.svg)](https://www.ruby-lang.org)
 [![Rails](https://img.shields.io/badge/Rails-8.1-CC0000.svg)](https://rubyonrails.org)
 
 [Why RailsAdminNext?](#why-railsadminnext) ◆ [Quick Start](#quick-start) ◆ [Installation](#installation) ◆ [Architecture](#architecture) ◆ [Security](#security) ◆ [Upgrading](#upgrading-from-railsadmin)
@@ -32,7 +32,7 @@ multi-bundler, jQuery-era machinery. RailsAdminNext keeps the admin and drops th
 - **⚡ Zero build step** — browser-native ESM over **importmap + Propshaft**; no Webpack/Vite/Sprockets, no `yarn build`, no generated pins.
 - **🧩 Turbo + Stimulus** — the jQuery / jQuery-UI / Bootstrap-JS / `@rails/ujs` stack is gone, replaced by engine-shipped Stimulus controllers; styling is hand-maintained vanilla CSS.
 - **🔒 Hardened & CDN-free** — a documented CSRF / clickjacking / mass-assignment / CSP posture ([SECURITY.md](SECURITY.md)) and **zero external CDN**, default or opt-in — every asset is self-hosted off a gem.
-- **🎯 One modern target** — Ruby ≥ 4.0.5, Rails ~> 8.1, ActiveRecord only, latest Chrome + Safari. No Mongoid, no multi-bundler / multi-Rails matrix, no legacy-browser CSS.
+- **🎯 One modern target** — Ruby ≥ 4.0.9, Rails ~> 8.1, ActiveRecord only, latest Chrome + Safari. No Mongoid, no multi-bundler / multi-Rails matrix, no legacy-browser CSS.
 - **↩️ Familiar** — `RailsAdminNext.config`, per-model `rails_admin_next do … end` blocks, and CanCanCan / Pundit authorization all work as before; upgrading from RailsAdmin is a mechanical rename.
 
 ## Quick Start
@@ -50,17 +50,21 @@ bin/rails s                            # then open http://localhost:3000/admin
 
 That's the whole setup — no `yarn add`, no asset build, no generated pins. The engine ships its own importmap and CSS.
 
-> **Prerequisites:** Ruby ≥ 4.0.5 · Rails ~> 8.1 · ActiveRecord · a [Propshaft][propshaft] + [importmap-rails][importmap] host (both are pulled in as dependencies). See [Installation](#installation) for the full walkthrough.
+> **Prerequisites:** Ruby ≥ 4.0.9 · Rails ~> 8.1 · ActiveRecord · a [Propshaft][propshaft] + [importmap-rails][importmap] host (both are pulled in as dependencies). See [Installation](#installation) for the full walkthrough.
 
 ## Requirements
 
-- Ruby >= 4.0.5
+- Ruby >= 4.0.9
 - Rails ~> 8.1
 - ActiveRecord (Mongoid is not supported)
 - [Propshaft][propshaft] and [importmap-rails][importmap] (both are pulled in as
   dependencies; RailsAdminNext serves its frontend over them, with no bundler or build step)
 - Latest stable Chrome or Safari for the admin's users (see [Browser support](#browser-support))
 
+RailsAdminNext expects **evergreen** hosts. The Ruby floor follows the latest stable Ruby
+patch release, and a release can raise it without a major version bump. Keep your app on
+current Ruby and Rails to keep receiving updates.
+
 [propshaft]: https://github.com/rails/propshaft
 [importmap]: https://github.com/rails/importmap-rails
 
@@ -83,6 +87,22 @@ The install generator mounts the engine, writes
 `config/initializers/rails_admin_next.rb`, and does nothing else — the engine ships its
 own importmap and CSS, so there is no `yarn add`, no asset build, and no generated pins.
 
+### Agent skill
+
+RailsAdminNext is a [Rails Hyperdrive][hyperdrive] companion gem. It ships a
+`rails-admin-next` skill that teaches coding agents this fork's API rather than upstream
+RailsAdmin's. In an app running Hyperdrive, sync installs the skill, and each later
+release updates it:
+
+```bash
+bin/rails hyperdrive:sync
+```
+
+The skill points agents at the `docs/*.md` files packaged in the gem, so its references
+always match the installed version.
+
+[hyperdrive]: https://github.com/rails-hyperdrive/rails-hyperdrive
+
 ## Features
 
 - CRUD any data with ease

data/Rakefile

@@ -8,6 +8,8 @@ Dir["lib/tasks/*.rake"].each { |rake| load rake }
 require "bundler"
 Bundler::GemHelper.install_tasks
 
+require "hyperdrive/skill_tasks"
+
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 

data/app/controllers/rails_admin_next/main_controller.rb

@@ -108,6 +108,17 @@ module RailsAdminNext
       model_config.send(action).with(controller: self, view: view_context, object: @object).visible_fields
     end
 
+    # Memoized, as export renders through index, which switches @action
+    def serialization_schema
+      @serialization_schema ||= begin
+        section = %i[export show].include?(@action.key) ? @model_config.send(@action.key) : @model_config.list
+        SerializationSchema.new(
+          section.with(controller: self, view: view_context, object: @object || @abstract_model.model.new),
+          include_associations: @action.key == :export
+        )
+      end
+    end
+
     def sanitize_params_for!(action, model_config = @model_config, target_params = params[@abstract_model.param_key], nested_in = nil)
       return unless target_params.present?
 

data/docs/UPGRADING.md

@@ -0,0 +1,495 @@
+# Upgrading from rails_admin to rails_admin_next
+
+`rails_admin_next` is the modernized fork of `rails_admin`: Rails 8.1 / Ruby 4.0 floor,
+ActiveRecord only, an importmap + Propshaft asset pipeline, a Stimulus + Turbo
+frontend (no jQuery, jQuery-UI, Bootstrap JS, or `@rails/ujs`), vanilla CSS with a
+latest-Chrome/Safari browser floor, and a hardened security posture. This guide covers
+the one-time changes a host app needs.
+
+The Ruby namespace is renamed **`RailsAdmin` → `RailsAdminNext`** (and `rails_admin` →
+`rails_admin_next`), so your initializer, engine mount, model macros, and route helpers
+need a mechanical rename. The **authorization contract is deliberately unchanged** — the
+`:access, :rails_admin` subject and the `admin.*` I18n namespace stay exactly as they were,
+so your CanCanCan abilities, Pundit policies, and translations need no edits.
+
+## 1. Gemfile
+
+Replace the upstream `rails_admin` gem with the fork (distributed via `git:`):
+
+```ruby
+# Gemfile
+gem 'rails_admin_next', git: 'https://github.com/6temes/rails_admin_next'
+```
+
+Remove the old `gem 'rails_admin'` line, then `bundle install`.
+
+## 2. Application code — rename the namespace
+
+Rename `RailsAdmin` → `RailsAdminNext` and `rails_admin` → `rails_admin_next` in your
+initializer, mount, per-model blocks, and route-helper calls:
+
+```ruby
+# config/initializers/rails_admin_next.rb  (renamed from config/initializers/rails_admin.rb)
+RailsAdminNext.config do |config|
+  config.model User do
+    # …
+  end
+
+  # DELETE this line if your old initializer had it — the option was removed
+  # (there is a single importmap + Propshaft pipeline now; leaving it in place
+  # only logs a deprecation warning):
+  # config.asset_source = :importmap
+end
+
+# config/routes.rb
+mount RailsAdminNext::Engine => '/admin', as: 'rails_admin_next'
+
+# per-model blocks
+class Team < ApplicationRecord
+  rails_admin_next do
+    field :name
+  end
+end
+
+# route helpers — these also hide in mailers and regular views
+# (`rails_admin_url(...)` → `rails_admin_next_url(...)`) and inside field blocks
+# (`bindings[:view].rails_admin.show_path(...)` → `bindings[:view].rails_admin_next.show_path(...)`)
+rails_admin_next.dashboard_path
+rails_admin_next.edit_path(model_name: 'team', id: team.id)
+```
+
+**Keep the mount alias `rails_admin_next`.** The engine's own views resolve routes through
+the `rails_admin_next` route proxy, so the mount must expose that helper name — either
+`as: 'rails_admin_next'` as above, or no `as:` at all (it defaults to the engine name).
+Aliasing the mount to something else to preserve old helper names (e.g. `as: 'rails_admin'`)
+breaks every engine page at render time with
+`undefined local variable or method 'rails_admin_next'`.
+
+Find every host-side call site that needs the rename with:
+
+```bash
+grep -rnE 'rails_admin_url|rails_admin_path|\.rails_admin\.' app config
+```
+
+Running `rails g rails_admin_next:install` writes the new initializer and mount for you.
+
+## 3. Icons (`link_icon` / `navigation_icon`)
+
+Font Awesome is **no longer shipped** (no icon font, no `font-awesome.css`). Icons now
+render as inline SVG, and the icon options take a **logical icon name** (a Symbol or
+String) instead of a Font Awesome class string:
+
+```ruby
+# Before
+RailsAdminNext.config do |config|
+  config.model Team do
+    navigation_icon 'fas fa-trophy'
+  end
+  config.actions do
+    # …
+    my_custom_action { link_icon 'fas fa-rocket' }
+  end
+end
+
+# After
+RailsAdminNext.config do |config|
+  config.model Team do
+    navigation_icon :list      # a logical name (see the list below)
+  end
+  config.actions do
+    my_custom_action { link_icon :show_in_app }
+  end
+end
+```
+
+Available logical names (see `RailsAdminNext::Icons::GLYPHS`):
+
+`:dashboard` (alias `:home`), `:list`, `:show` (alias `:info`), `:new` (alias `:add`/`:plus`),
+`:edit` (alias `:pencil`), `:delete` (aliases `:cancel`/`:times`), `:export`,
+`:history` (alias `:book`), `:show_in_app` (alias `:eye`), `:bulk_delete` (alias `:question`),
+`:collapse`, `:expand`, `:calendar`, `:check`, `:minus`, `:refresh` (alias `:sync`),
+`:trash`, `:move_right`, `:move_left`, `:move_up`, `:move_down`.
+
+**Legacy Font Awesome strings still given to `link_icon`/`navigation_icon` are handled
+gracefully**: the glyph is best-effort mapped to the nearest logical name and a deprecation
+warning is emitted (`RailsAdminNext.deprecator`); a value that can't be mapped renders no
+icon rather than raising. Migrate to logical names to silence the warning. If you relied on
+Font Awesome classes elsewhere in your own admin views, vendor Font Awesome yourself — the
+engine no longer provides it.
+
+## Authorization (no change needed)
+
+The authorization contract is held stable — **do not touch your abilities or policies**:
+
+- The access subject is `:rails_admin`.
+- Every action's authorization key (`:dashboard`, `:index`, `:show`, `:new`, `:edit`,
+  `:export`, `:destroy`, `:history`, `:show_in_app`) is unchanged.
+
+```ruby
+# This CanCanCan ability keeps working unchanged:
+can :access, :rails_admin
+```
+
+The access subject is deliberately frozen and locked by a spec in the gem — a renamed
+subject can fail *open* (a `cannot` rule that no longer matches silently grants access).
+
+## Asset prerequisites
+
+RailsAdminNext ships its frontend over **importmap + Propshaft** only — there is no
+build step and no Sprockets/Webpacker/Webpack/Vite support. The host app must use:
+
+- **Propshaft** (`config.assets.*` via `propshaft`), and
+- **importmap-rails**.
+
+Optional:
+
+- **Thruster** in front of the app for edge caching of the fingerprinted assets.
+- Set `config.assets.integrity_hash_algorithm` if you want Subresource Integrity on the
+  engine's self-hosted modules (off by default; same-origin hosting makes SRI low-value).
+
+## Browser support
+
+The frontend targets the **latest stable Chrome and Safari only**. This fork is an internal
+tool for teams that control their admin users' browsers; the old "Baseline 2023 /
+Firefox ≥ 111" contract is retired deliberately, and no legacy-browser fallbacks ship. The
+engine's CSS and JS assume `:has()`, `<dialog>`, popovers, CSS nesting, `oklch()`,
+`color-mix()`, `light-dark()`, `@starting-style`, and CSS anchor positioning.
+
+Two features are newer still: `closedby="any"` (backdrop light-dismissal of the inline-edit
+dialog) needs Chromium 134+ / Safari 26, and CSS anchor positioning needs Chromium 128+ /
+Safari 26 (dropdown menus are positioned by anchor CSS alone — no JS fallback ships).
+`field-sizing: content` (auto-growing textareas) is a Chromium-only enhancement — other
+browsers keep fixed-height textareas.
+
+## Styling: cascade layers and design tokens
+
+Bootstrap's SCSS is gone. Styling is hand-maintained vanilla CSS delivered through three
+cascade layers, declared in `rails_admin.css` (the layer names are a documented contract):
+
+- `ra.tokens` — design tokens (CSS custom properties)
+- `ra.framework` — the trimmed ex-Bootstrap component CSS
+- `ra.skin` — the engine's own widgets, icons, and admin skin
+
+Because all engine CSS is layered, **any unlayered host rule beats it** — a plain rule in
+your own stylesheet overrides the admin without `!important` or specificity games:
+
+```css
+/* host stylesheet — no layer, so it wins over everything the engine ships */
+.badge {
+  border-radius: 7px;
+}
+```
+
+### Supported override tokens (public API)
+
+Hosts may override these tokens (unlayered, e.g. `:root { --ra-primary: #663399; }`) and
+every derived color — button hover/active states, focus rings, alert tints, table tints,
+links — follows automatically:
+
+| Token | Role |
+| --- | --- |
+| `--ra-primary`, `--ra-secondary`, `--ra-success`, `--ra-info`, `--ra-warning`, `--ra-danger`, `--ra-light`, `--ra-dark` | brand and status colors |
+| `--ra-body-bg`, `--ra-body-color` | body surface and text |
+| `--ra-link-color` | link color (defaults to a tint of `--ra-primary`) |
+
+A single-color override applies to both light and dark schemes; hosts that want a tuned dark
+mode should override with their own pair:
+
+```css
+:root {
+  --ra-primary: light-dark(#663399, #a97fd6);
+}
+```
+
+**Every other `--ra-*` name is internal and may change without notice.**
+
+### Dark mode and the `color_scheme` knob
+
+The admin now follows the OS color-scheme preference automatically: every color token is a
+`light-dark()` pair, resolved against a `<meta name="color-scheme">` the layout renders from
+the new config knob:
+
+```ruby
+RailsAdminNext.config do |config|
+  config.color_scheme = :auto # default; :light or :dark pins the scheme
+end
+```
+
+Pin `:light` to keep the old always-light rendering. Two deliberate exceptions: the navbar is
+scheme-locked (`navbar_css_classes` express host intent — `navbar-dark bg-primary` stays a
+dark navbar under both schemes), and the Trix (ActionText) editor stays light-only for now.
+
+### Token mapping: `--bs-*` → `--ra-*`
+
+The Bootstrap `--bs-*` custom properties are gone. Renamed with the same meaning — read or
+override the new name:
+
+| Old | New | Note |
+| --- | --- | --- |
+| `--bs-body-bg` | `--ra-body-bg` | |
+| `--bs-body-color` | `--ra-body-color` | |
+| `--bs-body-font-family` | `--ra-body-font-family` | |
+| `--bs-body-font-size` | `--ra-body-font-size` | |
+| `--bs-body-font-weight` | `--ra-body-font-weight` | |
+| `--bs-body-line-height` | `--ra-body-line-height` | |
+| `--bs-body-text-align` | `--ra-body-text-align` | still undeclared by default; set it to opt in, exactly like Bootstrap's knob |
+| `--bs-breadcrumb-divider` | `--ra-breadcrumb-divider` | |
+| `--bs-font-monospace` | `--ra-font-monospace` | |
+| `--bs-font-sans-serif` | `--ra-font-sans-serif` | |
+| `--bs-gradient` | `--ra-gradient` | |
+| `--bs-gutter-x` / `--bs-gutter-y` | `--ra-gutter-x` / `--ra-gutter-y` | grid-scoped |
+| `--bs-table-bg` | `--ra-table-bg` | table-scoped; likewise `-accent-bg`, `-striped-bg`, `-striped-color`, `-active-bg`, `-active-color`, `-hover-bg`, `-hover-color` |
+
+Renamed with a value-space change (number → percentage):
+
+| Old | New |
+| --- | --- |
+| `--bs-bg-opacity: 0.5` | `--ra-bg-opacity: 50%` |
+| `--bs-text-opacity: 0.5` | `--ra-text-opacity: 50%` |
+
+Previously declared but consumed by nothing — now live semantic tokens (overriding the
+`--bs-*` name never did anything; the `--ra-*` name works): `--bs-primary` →
+`--ra-primary`, `--bs-secondary` → `--ra-secondary`, `--bs-success` → `--ra-success`,
+`--bs-info` → `--ra-info`, `--bs-warning` → `--ra-warning`, `--bs-danger` → `--ra-danger`,
+`--bs-light` → `--ra-light`, `--bs-dark` → `--ra-dark`.
+
+Removed — replaced by derivation (never override these; override the base token instead):
+the whole `-rgb` family (`--bs-primary-rgb` … `--bs-dark-rgb`, `--bs-white-rgb`,
+`--bs-black-rgb`, `--bs-body-color-rgb`, `--bs-body-bg-rgb`) is gone; utilities now derive
+translucency via `color-mix(in srgb, var(--ra-*) <pct>, transparent)`.
+
+Removed without replacement (declared but never consumed): the raw color ladder
+(`--bs-blue`, `--bs-indigo`, `--bs-purple`, `--bs-pink`, `--bs-red`, `--bs-orange`,
+`--bs-yellow`, `--bs-green`, `--bs-teal`, `--bs-cyan` — the code-pink role of `--bs-pink`
+lives on as the internal `--ra-code-color`), `--bs-white`, `--bs-gray`, `--bs-gray-dark`,
+`--bs-gray-100` … `--bs-gray-900` (the grays the CSS actually uses exist as internal
+`--ra-gray-*` tokens), and `--bs-position` (set by `.dropdown-menu-end` for Bootstrap's
+dropdown JS, which this engine does not ship).
+
+### Removed component CSS
+
+The flattened Bootstrap CSS was trimmed to what the engine actually renders. These component
+families were deleted as unreachable:
+
+| Removed family | If you relied on it |
+| --- | --- |
+| Carousel | No engine view renders one; ship your own carousel CSS/JS in custom actions. |
+| Tooltip (`.tooltip`, `.bs-tooltip-*`) | Bootstrap tooltips needed Bootstrap JS, which the engine does not ship; use the native `title` attribute or your own library. |
+| Popover component (`.popover`, `.bs-popover-*`) | Same as tooltips. (The native `popover` *attribute* is what the engine now uses for its dropdown menus.) |
+| Toasts | Engine flash messages render as alerts; `alert-*` stays supported. |
+| Offcanvas | Never emitted by engine views. |
+| Accordion | Sidebar groups are native `<details>`/`<summary>` now. |
+| Spinners (`.spinner-border`, `.spinner-grow`) | The engine's loading indicator is the `#loading` badge. |
+| Placeholders (loading skeletons) | Never emitted by engine views. |
+| Floating labels (`.form-floating`) | Engine forms use stacked labels. |
+| `.form-range` | No engine form renders a range input. |
+| Form validation (`.is-valid` / `.is-invalid` / `*-feedback` / `*-tooltip`) | Engine forms render server-side errors through their own `.error` + `.help-inline.text-danger` markup, which is kept. |
+| `.form-check` / `.form-switch` wrapper styling | Checkboxes/radios are native, tinted via `accent-color`; `.form-check-input` itself is still styled. |
+| jQuery-UI chrome | jQuery-UI is gone. |
+| wysihtml5 editor chrome | The editor was dropped; use ActionText/Trix. |
+| `.collapsing` | Bootstrap JS's collapse-transition class; sidebar collapse is a native `<details>`. |
+| `[data-bs-popper]` rules | Popper.js is not shipped. |
+| `.dropup` / `.dropend` / `.dropstart` | Engine menus only drop down (and flip above the toggle automatically near the viewport edge). |
+| Responsive tiers `sm` / `lg` / `xl` / `xxl` | The `.col-sm-*` grid columns engine forms emit survive; the responsive display/spacing/text utilities and `container-*` tiers are gone (a couple of `md` utilities remain). |
+| Print utilities (`.d-print-*`) | Gone; add your own print CSS if you print admin pages. |
+
+### The styled vocabulary (keep-list)
+
+The stylesheet keeps a deliberate keep-list even where no engine view currently emits the
+class: vocabularies that are host-facing configuration API remain styled and supported —
+
+- `.navbar-light` / `.navbar-dark` — the `navbar_css_classes` value space,
+- `alert-*` — the `flash_alert_class` value space,
+- `bg-*` utilities — badges, indicators, and the host navbar,
+- `.badge` colors,
+- `table-*` contextual rows — `row_css_class` conventions.
+
+Class names the stylesheet does not style are out of contract and may stay unstyled.
+
+## Markup changes
+
+Three widgets moved from Bootstrap markup to native platform primitives. Hand-rolled host CSS
+or JS that targeted the old DOM needs updating — `.modal.fade`, `.dropdown .show`, and the
+sidebar's `.collapse` no longer appear:
+
+| Widget | Was | Now |
+| --- | --- | --- |
+| Inline-edit modal | `.modal.fade` + `.modal-dialog` divs | native `<dialog id="modal" closedby="any">` |
+| Dropdown menus (filters, bulk actions) | `<a role="button">` toggles + `.dropdown .show` | `<button popovertarget>` toggles + `popover="auto"` menus, positioned with CSS anchor positioning |
+| Sidebar navigation groups | `.collapse` + Bootstrap collapse classes | native `<details>`/`<summary>` disclosures |
+
+## Required `belongs_to` associations
+
+A `belongs_to` your model actually requires is now rendered as required. Previously only a
+presence or numericality validator on the association or its foreign key was detected, and
+Rails registers the validator it adds for a required `belongs_to` with an `if:` condition that
+the detection skipped.
+
+`belongs_to_required_by_default` has been on since `load_defaults 5.0`. On `load_defaults 7.1`
+or later Rails also sets `belongs_to_required_validates_foreign_key = false`, which is what makes
+the presence validator conditional and invisible to the old detection — so this affects every
+plain `belongs_to` whose foreign key carries no validator of its own. For those fields:
+
+- the help text reads "Required." instead of "Optional."
+- a plain association select carries `required`, so the browser blocks submission while it is
+  empty; polymorphic association fields change help text and filter operators only, because
+  their partial does not apply the field's HTML attributes
+- the association select no longer offers its clear-selection entry
+- the index filter loses the "is present" and "is blank" operators
+
+An association declared with `default:` is left optional, since Rails fills it in a
+`before_validation` callback. If a model fills the association server-side some other way, the
+browser will now block a form the server would have accepted. Mark the field optional:
+
+```ruby
+RailsAdminNext.config Order do
+  edit do
+    field :customer do
+      optional true
+    end
+  end
+end
+```
+
+## Nested forms hide the link back to the parent
+
+A nested subform no longer renders the child's association back to the record being edited.
+Editing a `FieldTest` with `has_one :comment, as: :commentable` used to ask, from inside that
+form, which record the comment belonged to — a choice the parent had already made and that the
+nested save overwrote anyway.
+
+This widened along with the association's notion of an inverse. `inverse_of` now answers with
+the declared `inverse_of:`, otherwise the inverse ActiveRecord resolves for the reflection,
+otherwise a polymorphic `as:`. It previously answered only the declared option, so a pair that
+declared nothing on either side — the conventional case Rails resolves on its own — reported no
+inverse and the back-reference stayed on screen. Combined with required `belongs_to` detection
+above, that field could be marked required while being one only the nested save can fill.
+
+Two consequences worth checking in a host app:
+
+- A subform for a pair that relies on Rails' automatic inverse detection now hides one more
+  field than before, and its key is no longer permitted inside `<assoc>_attributes[...]` either.
+  Only at nested depth: editing the child on its own still permits its own association, which is
+  a legitimate way to set it.
+- `field.inverse_of` in your own configuration blocks now returns a symbol for associations
+  that previously returned `nil`.
+
+**Narrowing the allowlist is a security fix, for collections.** Saving a singular association re-applies
+the owner to the child, so a submitted back-reference never survived there. A collection does not:
+`assign_nested_attributes_for_collection_association` assigns straight onto an already-associated
+record, so a crafted back-reference inside `<assoc>_attributes[n]` moved that child onto a
+different parent — one the submitter may have had no rights over. Dropping the key from the
+allowlist closes it, because it never reaches the assignment.
+
+`inverse_of: false` on the association is honoured, as in Rails. To keep the back-reference
+visible — and permitted — for one field without touching the model, disable the parent field's
+inverse. On a collection that re-opens the re-parenting described above, so scope it to the one
+field that needs it:
+
+```ruby
+RailsAdminNext.config FieldTest do
+  edit do
+    field :comment do
+      inverse_of { false }
+    end
+  end
+end
+```
+
+Note the block: a bare `inverse_of nil` reads the option rather than setting it.
+
+## The show action answers HTML by default
+
+`show` used to declare its JSON format before its HTML one, so a request carrying no
+`Accept` header — `curl`, a bare `fetch()`, most HTTP client libraries — arrived as
+`*/*`, matched every registered type, and got JSON back. Every other action answered
+HTML for the same request.
+
+It now declares HTML first. A client that explicitly sends `Accept: application/json`,
+or requests the `.json` extension, is unaffected.
+
+If you have a script relying on the unheadered JSON response, send the header or use
+`.json`:
+
+```bash
+curl -H 'Accept: application/json' https://example.com/admin/player/1
+curl https://example.com/admin/player/1.json
+```
+
+The JSON branch renders only the fields the show view displays (see below).
+
+## JSON and XML serialize only configured fields
+
+The index action's `.json`/`.xml`, the show action's `.json`, and the export action's JSON/XML
+used to serialize every attribute of the record, and export passed the submitted `schema` straight
+to `to_json`/`to_xml` — so any `methods` or `include` name in it was called on every record.
+
+They now serialize only what the matching section shows: `list` for index, `show` for show,
+`export` for export. Index and show also keep the foreign keys of the `belongs_to` associations
+they display. A submitted export `schema` is intersected with the export fields, and `except` is
+ignored.
+
+If a client relied on a column the section doesn't show, add that field to the section.
+
+## Pundit: a model with no policy Scope lists nothing
+
+A model whose policy defines no `Scope` used to list every record. It now lists none: the
+list, export, bulk delete and dashboard count all return an empty set. Bulk delete deletes
+whatever the scope returns, with no per-record check, so "no Scope" can't mean "everything".
+
+Define a `Scope` for each model the admin exposes:
+
+```ruby
+class PlayerPolicy < ApplicationPolicy
+  class Scope < ApplicationPolicy::Scope
+    def resolve
+      scope.all
+    end
+  end
+end
+```
+
+CanCanCan hosts are unaffected.
+## Removed: options deprecated before RailsAdmin 3.0
+
+These six were deprecated upstream between 2019-07 and 2022-01 and had no effect for
+years. They are gone rather than carried into this gem's 1.0:
+
+| Removed | What to do |
+| --- | --- |
+| `config.total_columns_width=` | Nothing. It had no effect. |
+| `config.sidescroll=` | Nothing. Horizontal scroll with frozen columns is always on. |
+| `list.sidescroll` | Nothing. Same as above. The field-level `sticky?` still controls which columns freeze. |
+| `list.sort_reverse` | Nothing. It had no effect. The field-level `sort_reverse?` is unrelated and unaffected. |
+| `momentjs_format` | Nothing. Date/time fields are native HTML5 inputs and render per the browser locale. |
+| `eager_load?` | Rename to `eager_load`. |
+| `delete_key` (`:multiple_file_upload`) | Rename to `delete_value`. |
+
+`register_deprecated_instance_option` itself stays — extensions and host apps use it for
+their own options.
+
+## Dropped support
+
+These are intentionally gone — migrate off them before upgrading:
+
+- **Mongoid** — RailsAdminNext is ActiveRecord only.
+- **Sprockets / Webpacker / Webpack / Vite** — importmap + Propshaft only.
+- **Standalone WYSIWYG/code editor field types** (`bootstrap-wysihtml5`, `froala`, and the
+  cdnjs-backed `:ck_editor` / `:code_mirror` / `:simple_mde`) — they loaded JS/CSS from cdnjs.
+  Migrate those fields to `:action_text` (self-hosted Trix rich text) or a plain `:text` textarea
+  instead. The engine now has **zero external CDN** usage, default and opt-in.
+- **Non-ActiveStorage attachment libraries** (CarrierWave, Paperclip, Shrine, Dragonfly,
+  Refile) — RailsAdminNext detects **ActiveStorage** (and ActionText/Trix) attachments only.
+  Migrate file/image columns to ActiveStorage before upgrading. Image variants are processed
+  with **libvips** via `image_processing` + `ruby-vips` (set
+  `config.active_storage.variant_processor = :vips`); install the libvips system library
+  (`brew install vips` / `apt-get install libvips-dev`) — ImageMagick is no longer required.
+- **Configurable app branding (`main_app_name`)** — the navbar brand and page `<title>` are
+  hardcoded to "Rails AdminNext"; the config option is gone. Fork
+  `app/views/layouts/rails_admin_next/_navigation.html.erb` and `content.html.erb` in your
+  host app if you need custom branding.
+
+## History / audit table
+
+The gem owns **no** history table. Auditing remains host/PaperTrail territory, so there is
+no gem migration to run — your existing `rails_admin_histories` table (if any) is unaffected.

data/docs/security.md

@@ -0,0 +1,72 @@
+# Security posture
+
+The admin is a privileged surface. This engine ships the request-forgery, framing, and
+destructive-action controls itself; a few things are left for the host to opt into.
+
+## Always on
+
+- **CSRF.** `protect_from_forgery(with: :exception)` is hardcoded. A non-GET request without a
+  valid token is rejected (`ActionController::InvalidAuthenticityToken` → HTTP 422). There is no
+  host-configurable forgery option to weaken it.
+- **Clickjacking.** Every admin response carries `X-Frame-Options: SAMEORIGIN`.
+- **Export.** The CSV/JSON/XML data stream requires a non-GET, CSRF-protected request; `GET` only
+  renders the export form, so the table can't be exfiltrated via a crafted link.
+- **Serialization.** JSON and XML output is limited to the fields the section shows (`list`,
+  `show` or `export`). A submitted export `schema` is intersected with the export fields, so it
+  can't name a hidden column, an association the export doesn't show, or a method to call.
+- **Pundit scopes fail closed.** A model whose policy has no `Scope` lists no records, rather
+  than all of them.
+- **Destructive actions.** `delete` and `bulk_delete` render a confirmation page and additionally
+  carry `data-turbo-confirm` on the destructive submit (Turbo's confirmation, not `@rails/ujs`).
+- **Mass assignment.** Submitted attributes are sliced to the model config's `visible_fields`
+  before `permit!`, at the top level and at every nested depth, regardless of the submitted
+  nested-attributes cardinality (hash or array). At nested depth the slice also drops the child's
+  link back to the record being edited — the field the subform does not draw — so a crafted
+  back-reference cannot move a nested record onto a different parent.
+
+## Content Security Policy (opt-in)
+
+The engine enforces **no** CSP by default. When you opt in, it applies the policy per-request to
+admin responses only (never to the host app) and threads a per-request nonce onto the tags it
+emits — the importmap JSON, the import entry point and its module preloads, the index
+column-width `<style>`, and the engine's stylesheet and style-preload links — so a `:self` +
+nonce policy does not block the admin's own assets.
+
+```ruby
+# config/initializers/rails_admin_next.rb
+RailsAdminNext.config do |config|
+  config.content_security_policy do |policy|
+    policy.default_src :self
+    policy.script_src  :self
+    policy.style_src   :self, :unsafe_inline # see note below
+    policy.img_src     :self, :data
+    policy.font_src    :self
+    policy.connect_src :self
+  end
+end
+```
+
+Tune it without breaking pages first by reporting only:
+
+```ruby
+RailsAdminNext.config do |config|
+  config.content_security_policy(report_only: true) do |policy|
+    policy.default_src :self
+  end
+end
+```
+
+> **Note on `style-src`.** The admin still renders five inline `style="…"` attributes, which a CSP
+> nonce cannot cover (nonces apply to `<script>`/`<style>` elements, not style attributes), so a
+> `style-src` directive needs `:unsafe_inline` for now. The engine's own `<style>` element (the
+> index column-width block) is nonced. The remaining attributes:
+>
+> - the `#loading` badge's positioning in the layout, and the delete-notice `<li>` spacing —
+>   static values, removable by moving them into the stylesheet;
+> - the file-upload delete toggle's initial `display:none` — conditional initial state, removable
+>   by switching to the `hidden` attribute;
+> - the dashboard's `.progress` margin (static) and each progress bar's `width: N%` (a per-row
+>   dynamic value — the one that genuinely resists removal; it would need the nonced-`<style>`
+>   route or a native `<progress>` element).
+>
+> Once those five are reauthored, `:unsafe_inline` can be dropped.

data/docs/upstream-parity.md

@@ -0,0 +1,145 @@
+# Upstream parity
+
+Assessed through upstream `2dfd05f1` (2026-10-30). Fork point: `d8e0809e` (2025-09-14).
+
+Divergence from the fork point: 792 files, +21,203 / −73,569 lines.
+
+## How this fork tracks upstream
+
+RailsAdminNext is a hard fork of [railsadminteam/rails_admin](https://github.com/railsadminteam/rails_admin). It is **never merged or rebased from upstream**, and it cannot be: the fork deleted whole subsystems upstream still ships — the Mongoid adapter, the npm/webpack build, jQuery and `@rails/ujs`, Bootstrap's JavaScript, Appraisal, CarrierWave. Replaying this fork's history onto a moving upstream would conflict with every commit touching any of them, by construction.
+
+Instead, upstream work is absorbed by **reimplementation**: read the upstream commit, judge whether the underlying problem exists here, and write the fix in this codebase's terms. A port therefore need not — and often should not — match upstream's diff. Deliberate divergences are recorded below so they are not "corrected" back later.
+
+This means `git rev-list --count upstream/master...master` is not a progress measure. It counts commits never merged, so it does not fall when work is absorbed and it grows every time upstream moves. **This ledger is the state.** The watermark above records what has been assessed; the table records the verdict for each commit, including the ones deliberately skipped.
+
+## Verdicts
+
+Commits are listed newest first, as `git log` reports them.
+
+| upstream | subject | verdict | ours |
+|---|---|---|---|
+| `2dfd05f1` | Test ferrum 0.19.2 with flatten mode on JRuby | n/a — JRuby leg over Appraisal gemfiles; neither exists here | — |
+| `bf8f645c` | Replace nested_form with RailsAdmin's own nested form implementation | partly relevant — per-controller `<template>` and button controls already here; unsaved-row remove, self-reference recursion, placeholder collision and the dummy belongs_to still apply | [#73](https://github.com/6temes/rails_admin_next/issues/73) |
+| `6e27f4d3` | Let the adapter narrow a scope, instead of merging it here | n/a — one AR adapter; the controller's merge is already its vocabulary, no behaviour change | — |
+| `20f8f29a` | Narrow a listing by the scope it selects before it is paginated | partly adapted — pre-pagination done; export and bulk delete ignore the tab, and remote pickers get it | [#60](https://github.com/6temes/rails_admin_next/issues/60) |
+| `7e5a7d67` | Keep the browser driver off a version the suite hangs on | partly relevant — the pin is JRuby-only (n/a); the missing job timeout matches this fork's apt-step hangs | [#74](https://github.com/6temes/rails_admin_next/issues/74) |
+| `1e0bd4fd` | Say what an upload needs from an embedded document | n/a — embedded documents are Mongoid; no upload docs here | — |
+| `6651f64d` | Say which records associated_collection_scope governs | n/a — the option isn't documented here, so nothing to correct | — |
+| `51d7321a` | Look up a registered visible block by the option's own name | relevant — measured: redeclaring a field drops its visible block; `admin?` raises NameError | [#64](https://github.com/6temes/rails_admin_next/issues/64) |
+| `e67edd00` | Escape a field name before it stands in for a selector | n/a — the filter container is found by `getElementById`; other selectors use `CSS.escape` or quoted values | — |
+| `11cd3e53` | Leave out a column the queried term could never fit | relevant — measured: PG raises NumericValueOutOfRange for a 10-digit term on int4 | [#56](https://github.com/6temes/rails_admin_next/issues/56) |
+| `2d9f951f` | Have no enumeration rather than crash when there's no _enum method | relevant — measured: enum without a source crashes filter_operators; native PG enums hit it unconfigured | [#58](https://github.com/6temes/rails_admin_next/issues/58) |
+| `c4b64ede` | Document sort_by's array and hash forms | n/a — sort_by isn't documented here; the forms are supported | — |
+| `cbed4c42` | Fall back to the guessed encoding when a CSV export leaves it blank | n/a — measured: blank does what the form says here (leaves encoding untouched); the fallback is a no-op on the connection encoding | — |
+| `8748af05` | Bind the controller and view before reading a model's list scopes | relevant — measured: both reads are unbound | [#62](https://github.com/6temes/rails_admin_next/issues/62) |
+| `3e26f685` | Keep a serialized value's wrapper class out of the text an admin edits | relevant — measured: every AR `store` round-trip raises DisallowedClass | [#63](https://github.com/6temes/rails_admin_next/issues/63) |
+| `8b7f686b` | Let a requested sort win over has_paper_trail's own version order | relevant — `order` appended after paper_trail's association order | [#69](https://github.com/6temes/rails_admin_next/issues/69) |
+| `e9e13ebf` | Recognize a native timestamptz column as a timestamp field | relevant — measured: Rails 8.1.4 PG reports `:timestamptz`, which the registry rejects | [#55](https://github.com/6temes/rails_admin_next/issues/55) |
+| `0c6b8e9d` | Version 4.0.0.beta2 | n/a — upstream release chore | — |
+| `d96845da` | [Security] Fail closed when Pundit policy scope is undefined | relevant — the adapter rescued a missing Scope with `model.all`; fixed with plain AR `none` (no repository indirection needed) | [#77](https://github.com/6temes/rails_admin_next/pull/77) |
+| `a6cf6bb0` | [Security] Limit JSON/XML serialization to the configured fields | partly adapted — the GET gate was already here; methods/hidden columns via `schema` and full-row index/show output fixed; the default never calls virtual fields | [#77](https://github.com/6temes/rails_admin_next/pull/77) |
+| `fca081f2` | Version 4.0.0.beta | n/a — upstream release chore | — |
+| `00ddcd06` | Drop the dummy app's tooling for asset modes that no longer exist | n/a — none of those files are tracked here | — |
+| `d593bcaf` | Serve the dummy app's own JavaScript through every asset pipeline | n/a — one pipeline; the host entry is an ESM module importing Turbo | — |
+| `72bdd18d` | Let any callable serve as asset_source | n/a — `asset_source=` is a deprecated no-op here | — |
+| `812109cf` | Put the :external stylesheet where a JS build will not eat it | n/a — the installer writes only an initializer | — |
+| `9ed33f69` | Keep the dummy app's test hooks out of development | n/a — the only test hook here is invisible | — |
+| `7cc5e292` | Keep the dummy app's cookies readable, and cover CSRF both ways | partly relevant — the json pin is moot on Rails 8.1.4; the CSRF acceptance coverage gap applies | [#76](https://github.com/6temes/rails_admin_next/issues/76) |
+| `fd0bf316` | Drop the docs left behind by the asset rework | n/a — docs here mention those pipelines only as removed | — |
+| `3af6946c` | Flush rich-text editors before the modal submits | n/a — Trix writes its input on every change; no submit-time editor remains | — |
+| `a16b425f` | Test carrierwave 3.x and 4.x within the existing CI matrix | n/a — CarrierWave removed | — |
+| `8302cc29` | Lower a search term with String#downcase | adapted — already `downcase`; no `mb_chars` left | — |
+| `63ebb9ac` | Ask whether an enum is null, not whether it equals '' | relevant — measured: PG rejects `= ''` on an integer enum | [#57](https://github.com/6temes/rails_admin_next/issues/57) |
+| `749cbe75` | Let associated_collection_scope decide the order it asks for | relevant — scope applied before the reorder; the swap must follow #60 | [#61](https://github.com/6temes/rails_admin_next/issues/61) |
+| `47da8e99` | Refresh SimpleMDE editors when their tab is shown | n/a — no layout-measuring editor ships here | — |
+| `4443ab35` | Ship a prebuilt asset bundle; collapse config.asset_source | n/a — already a single zero-build importmap + Propshaft path | — |
+| `478484fb` | CI: install ImageMagick against a refreshed package list | n/a — the step here already runs `apt-get update` and `-y`; the failure here is a stall (#74) | — |
+| `a6f4c5ad` | Fix the viewport meta tag's name attribute | relevant — the identical malformed tag is in `_head.html.erb` | [#72](https://github.com/6temes/rails_admin_next/issues/72) |
+| `88e6df4d` | Strip a leading :: when deriving a model's config registry key | relevant — measured: config ignored and the model listed twice | [#70](https://github.com/6temes/rails_admin_next/issues/70) |
+| `a5607f24` | Use label_plural in bulk delete flash messages | relevant — measured: translated plural ignored | [#71](https://github.com/6temes/rails_admin_next/issues/71) |
+| `7b60193b` | Let the page catch up before reading the database | adapted — fixed independently here | [#23](https://github.com/6temes/rails_admin_next/pull/23) |
+| `ef3e3f57` | Keep one dead browser from failing the examples after it | partly relevant — the driver restore applies; the startup-timeout half is deferred (never seen in ~60 runs) | [#75](https://github.com/6temes/rails_admin_next/issues/75) |
+| `cc293dea` | Wait for the autocomplete menu itself, not for one of its entries | n/a — waits here use counts or text the stale menu can't satisfy; the widget renders once per query (as `77e5d0bc`) | — |
+| `d3cfba1d` | Render the list for a filter URL written by hand | relevant — measured: seven malformed shapes 500, one specific to this fork | [#65](https://github.com/6temes/rails_admin_next/issues/65) |
+| `ede4e77b` | Split the adapter layer into a Reflection and a Repository | declined — multi-ORM refactor, one adapter here; four embedded fixes filed separately | [#59](https://github.com/6temes/rails_admin_next/issues/59), [#66](https://github.com/6temes/rails_admin_next/issues/66), [#67](https://github.com/6temes/rails_admin_next/issues/67), [#68](https://github.com/6temes/rails_admin_next/issues/68) |
+| `897ffc13` | Fix _discard leaking into SQL for multi-select enum filters | adapted — server half only; the client half was already stronger here (disabled options), so upstream's JS was deliberately not ported | [#36](https://github.com/6temes/rails_admin_next/pull/36) |
+| `11f214f6` | Remove config options deprecated before RailsAdmin 3.0 | adapted — the deprecator half already shipped; this removed the six options | [#40](https://github.com/6temes/rails_admin_next/pull/40) |
+| `cbea80b1` | Match GET in http_methods case-insensitively | adapted — `Actions::Base#linkable?` | [#38](https://github.com/6temes/rails_admin_next/pull/38) |
+| `9336ec71` | Drop Proc bounds from a field's length validation | adapted — widened beyond upstream to Symbol bounds, which crash identically | [#35](https://github.com/6temes/rails_admin_next/pull/35) |
+| `331841ea` | Remove duplicate global assignment of window.jQuery | n/a — jQuery removed | — |
+| `71852cd8` | Fix malformed rubocop directive comment | n/a — measured: standardrb clean, and no `has_option?` directive here to malform | — |
+| `cfc17e0d` | Pin json to < 3 for the test suite | n/a — dependency churn, Dependabot's job | — |
+| `316c299d` | Change default response format of the show action to HTML | adapted | [#39](https://github.com/6temes/rails_admin_next/pull/39) |
+| `0f4f765e` | Use the same widget which works for nullable booleans also for non nullable | declined — cosmetic consistency change; alters every boolean field in every host app and fixes no defect | — |
+| `495cc864` | Filter ferrum 0.18's console stack-frame log lines | adapted — landed before the cuprite bump that would trigger it | [#37](https://github.com/6temes/rails_admin_next/pull/37) |
+| `2eed28e1` | Fully specify all ESM imports with an extension | n/a — measured: every relative import in `src/` already carries `.js`; browser-native ESM requires it | — |
+| `e8dec57a` | Upgrade @hotwired/turbo-rails to resolve security warning | n/a — turbo comes from the `turbo-rails` gem (2.0.23), which Dependabot reads | — |
+| `07b2066a` | Replace `asset-url` with `url` in Sass files | n/a — no Sass; one hand-owned CSS file | — |
+| `a0946615` | Drop support for Rails 6.x and Ruby 2.5/2.6 | n/a — this fork is Rails ~> 8.1 / Ruby >= 4.0.9 only | — |
+| `0543cb3f` | Revert npm package.json version ahead of actual publish | n/a — no npm package | — |
+| `cf7b112e` | Run Prettier on migrated docs | n/a — upstream's vendored wiki | — |
+| `1c2b92a3` | Rewrite wiki cross-links to relative docs/ links | n/a — upstream's vendored wiki | — |
+| `70ca765e` | Merge wiki history into docs/ | n/a — upstream vendored its GitHub wiki; this fork ships its own docs | — |
+| `0690a5e6` | Start development for 4.0.0 | n/a — upstream release chore | — |
+| `50fbbcd9` | Remove @babel/runtime as a direct dependency | n/a — no npm build here | — |
+| `e4ad87b7` | Replace deprecated jQuery functions with native ones | n/a — jQuery removed | — |
+| `77e5d0bc` | Improve intermittent autocomplete test failures due to stale element | n/a — measured: the widget stamps and aborts its own requests, and each query renders once | [#18](https://github.com/6temes/rails_admin_next/issues/18) |
+| `26bb8763` | Declare JavaScript package is a module | n/a — no npm package | — |
+| `336845f4` | Remove string mutation | adapted | [#16](https://github.com/6temes/rails_admin_next/pull/16) |
+| `b72badeb` | Add a "sass" entry point to package.json | n/a — no npm/webpack build | — |
+| `9b21e3ba` | Update rails/ujs NPM package | n/a — UJS removed, Turbo replaces it | — |
+| `ca2d0954` | Use a non-beta trix package in dummy_app | n/a — trix is self-hosted from `action_text-trix`, not an npm pin | — |
+| `1f681b48` | Add nonce to css/js tags | adapted — `csp_meta_tag` deliberately left out, see below | [#22](https://github.com/6temes/rails_admin_next/pull/22) |
+| `54a23401` | Add belongs_to optional/required support to `required?` | adapted | [#13](https://github.com/6temes/rails_admin_next/pull/13) |
+| `c18592a1` | Draw routes before the suite goes multi-threaded | adapted — premise corrected, see PR | [#17](https://github.com/6temes/rails_admin_next/pull/17) |
+| `91e9cca8` | Resolve the inverse of a polymorphic association | adapted — 3 divergences, see below | [#14](https://github.com/6temes/rails_admin_next/pull/14) |
+| `8bffeb61` | Pin vite-plugin-ruby below 5.2 | n/a — no vite | — |
+| `9f03412d` | Fix RuboCop offense in main_controller_spec | n/a — linting is Standard Ruby | — |
+| `17b64251` | Avoid carrierwave versions that pull in mimemagic | n/a — CarrierWave removed | — |
+| `703e4894` | Add Rails 8.1 support | n/a — this fork is Rails ~> 8.1 only | — |
+| `9881e254` | Add test for editing a nested one widget item | adapted — driven through this fork's markup | [#15](https://github.com/6temes/rails_admin_next/pull/15) |
+| `47d913fe` | Fix flaky locale spec for Datetimepicker widget | n/a — native HTML5 date/time inputs replaced the widget | — |
+| `ec685453` | Don't auto-require the appraisal gem | n/a — Appraisal removed | — |
+
+## Standing divergences
+
+Where a port deliberately differs from upstream's own patch. Each is correct *for this fork*; changing one to match upstream would reintroduce a bug.
+
+**`Association#inverse_of`** (from `91e9cca8`) resolves the declared `inverse_of:`, then the inverse ActiveRecord resolves for the reflection, then a polymorphic `as:` — and honours `inverse_of: false`. Upstream reads only the declared option and `as`.
+
+- The middle step exists because this fork is ActiveRecord-only. Upstream's adapter also serves Mongoid, which resolves no inverse, so `as` is the only source available to both. Without the middle step, a conventional pair that declares nothing on either side reports no inverse and keeps rendering its back-reference.
+- Honouring `inverse_of: false` matters because `false.try(:to_sym)` is `nil`, so upstream's `|| as` silently reinstates an inverse the host explicitly declined.
+- The order is load-bearing. Reading the declared option first is what keeps a polymorphic `belongs_to` that declares an inverse from raising inside Rails' reflection, where the class cannot be computed.
+
+**`FormBuilder#nested_field_association?`** (from the same commit) limits its hoisted name-match branch to association fields. Upstream's hoist is unconstrained. A polymorphic `as:` is never validated against the child class, so without the limit a plain column sharing that name can be suppressed from a subform.
+
+**`sanitize_params_for!`** drops the parent's inverse from the nested allowlist, which upstream does not do at all — its permitted keys are derived purely from the visible fields. Hiding the back-reference without narrowing the allowlist left a collection subform re-parentable through a crafted `<assoc>_attributes[n]`, since `assign_nested_attributes_for_collection_association` assigns straight onto an already-associated record ([#24](https://github.com/6temes/rails_admin_next/pull/24)).
+
+**`Field::Base#valid_length` drops Symbol bounds as well as Proc ones** (from `9336ec71`), and drops them only from the three keys that get compared (`LENGTH_BOUNDS`). Upstream drops every Proc-valued entry and no Symbols at all.
+
+- ActiveModel sanctions four bound types and resolves Proc and Symbol against the record at validation time, so neither can be compared against the column limit. Measured here: `minimum: :some_method` raised the same `ArgumentError` upstream's fix addresses for Procs, and a surviving `maximum: :some_method` rendered "Length up to max_len" as help text.
+- The narrowing to three keys exists because `valid_length` is a `register_instance_option` that host apps read. Rejecting every Proc, as upstream does, would also strip `if:`/`unless:` conditions from the hash.
+- `:in` and `:within` need no entry: ActiveModel collapses them to `:minimum`/`:maximum` at validator construction, and a Proc passed as `:in` raises at declaration time.
+
+**`StatementBuilder#to_statement` excludes `between` from the `_discard` strip** (from `897ffc13`), and strips only when the array actually contained the sentinel. Upstream strips unconditionally.
+
+- `between` reads its value array by index, so removing an element shifts the range ends. Measured: `["ignored", "_discard", "20"]` became a `>= 20` filter where it had been `<= 20`.
+- An array that arrived empty is not an array the strip emptied. A date filter legitimately submits `{v: [], o: "today"}`, carrying its meaning in the operator alone; returning early on any empty array breaks it.
+- Upstream's client-side half is deliberately not ported. `filter_box_controller` here sets `disabled` on the sentinel options in multi-select mode, not merely `hidden`, and a disabled `<option>` is excluded from form submission — a stronger guarantee than upstream's deselect.
+
+**The engine's stylesheet and style-preload tags carry the CSP nonce** (from `1f681b48`), but `csp_meta_tag` does not ship. Turbo reads that meta to re-nonce scripts it re-activates, and this engine renders no body script for it to re-activate; the nonce generator here is also per-request random, which a cached Turbo snapshot would carry stale. Adding the meta wants that generator decision alongside it.
+
+## Assessing the next batch
+
+```bash
+git fetch upstream
+git log --oneline --first-parent 897ffc13..upstream/master
+```
+
+`--first-parent` is load-bearing. Upstream folds whole histories in from time to time — `70ca765e` merged its GitHub wiki into `docs/`, and a plain `git log` across it turns an 18-commit batch into 1301, the extra 1283 being someone else's markdown. Check anything that is a merge (`git log -1 --format='%P %s' <sha>`) for what it actually brought in: vendored docs are one row, a merged feature branch needs its commits triaged individually.
+
+Triage each commit by the **underlying problem**, not by the API, selector, or library its diff happens to touch. State the problem without naming any of them; if that sentence describes something possible here, the commit is relevant even when its diff is entirely in code this fork deleted.
+
+`77e5d0bc` above is the cautionary case, and it cuts both ways. It was first dismissed as jQuery-UI-only, which was the wrong reason — the race it describes is stated in terms of a selector, and dismissing it on that vocabulary is exactly the mistake the rule above exists to prevent. But the CI failure that seemed to confirm the re-triage turned out to be an unrelated bug: an example reading the database before the server had answered ([#23](https://github.com/6temes/rails_admin_next/pull/23)). The widget itself stamps and aborts its requests, and instrumenting it showed one render per query, so the upstream race has no counterpart here.
+
+**A coincident failure is not confirmation.** Look past a commit's vocabulary to decide whether it *could* apply, then measure this fork's own code before concluding that it does.

data/lib/rails_admin_next/config/actions/export.rb

@@ -22,7 +22,8 @@ module RailsAdminNext
             # table with attacker-chosen columns; the export form posts back to this same action.
             if format && !request.get?
               request.format = format
-              @schema = HashHelper.symbolize(params[:schema].slice(:except, :include, :methods, :only).permit!.to_h) if params[:schema] # to_json and to_xml expect symbols for keys AND values.
+              serialization_schema # built while @action is still export
+              @schema = serialization_schema.sanitize(params[:schema].slice(:include, :methods, :only).permit!.to_h) if params[:schema]
               @objects = list_entries(@model_config, :export)
               index
             else

data/lib/rails_admin_next/config/actions/index.rb

@@ -66,7 +66,7 @@ module RailsAdminNext
                       @objects.collect { |object| {id: object.id.to_s, label: object.send(@model_config.object_label_method).to_s} }
                     end
                   else
-                    @objects.to_json(@schema)
+                    @objects.to_json(@schema || serialization_schema.default)
                   end
 
                 if params[:send_data]
@@ -77,7 +77,7 @@ module RailsAdminNext
               end
 
               format.xml do
-                output = @objects.map { |object| object.serializable_hash(@schema || {}) }.to_xml(root: @abstract_model.model.model_name.plural)
+                output = @objects.map { |object| object.serializable_hash(@schema || serialization_schema.default) }.to_xml(root: @abstract_model.model.model_name.plural)
                 if params[:send_data]
                   send_data output, filename: "#{params[:model_name]}_#{DateTime.now.strftime("%Y-%m-%d_%Hh%Mm%S")}.xml"
                 else

data/lib/rails_admin_next/config/actions/show.rb

@@ -24,7 +24,7 @@ module RailsAdminNext
             # registered type, so Rails falls back to whichever is declared first.
             respond_to do |format|
               format.html { render @action.template_name }
-              format.json { render json: @object }
+              format.json { render json: @object.to_json(serialization_schema.default) }
             end
           end
         end

data/lib/rails_admin_next/extensions/pundit/authorization_adapter.rb

@@ -40,11 +40,13 @@ module RailsAdminNext
 
         # This is called when needing to scope a database query. It is called within the list
         # and bulk_delete/destroy actions and should return a scope which limits the records
-        # to those which the user can perform the given action on.
+        # to those which the user can perform the given action on. A model with no policy
+        # Scope gets no records: bulk_delete deletes whatever this returns without a
+        # per-record check, so a forgotten Scope must not mean "everything".
         def query(_action, abstract_model)
           @controller.send(:policy_scope, abstract_model.model.all)
         rescue ::Pundit::NotDefinedError
-          abstract_model.model.all
+          abstract_model.model.none
         end
 
         # This is called in the new/create actions to determine the initial attributes for new

data/lib/rails_admin_next/support/serialization_schema.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rails_admin_next/support/hash_helper"
+
+module RailsAdminNext
+  # The options handed to to_json/serializable_hash, limited to what a section
+  # shows. Both serializers call every name under `methods` and `include` on each
+  # record, and serialize every attribute when `only` is missing, so a requested
+  # schema is only ever intersected with this, never passed through.
+  class SerializationSchema
+    def initialize(section, include_associations:)
+      @section = section
+      @include_associations = include_associations
+    end
+
+    # Attributes only: a virtual field need not be a method on the record, so
+    # calling it unasked could raise where the plain serialization never did.
+    def default
+      {only: allowed[:only]}
+    end
+
+    def sanitize(requested)
+      requested = HashHelper.symbolize(requested)
+      schema = filter(requested, allowed)
+      if @include_associations && requested[:include].is_a?(Hash)
+        schema[:include] = requested[:include].each_with_object({}) do |(name, value), included|
+          next unless value.is_a?(Hash) && allowed[:include].key?(name)
+
+          included[name] = filter(value, allowed[:include][name])
+        end
+      end
+      schema
+    end
+
+    private
+
+    def allowed
+      @allowed ||= begin
+        fields = @section.visible_fields
+        names = field_names(fields.select { |f| !f.association? || f.association.polymorphic? })
+        if @include_associations
+          names[:include] = fields.select { |f| f.association? && !f.association.polymorphic? }.to_h do |field|
+            associated = field.associated_model_config.export.with(@section.bindings.merge(object: field.associated_model_config.abstract_model.model.new))
+            [field.name, field_names(associated.visible_fields.reject(&:association?))]
+          end
+        else
+          # The section already shows these associations, so their keys expose nothing more
+          names[:only].concat(fields.select { |f| f.association? && f.association.type == :belongs_to && !f.association.polymorphic? }
+            .flat_map { |f| Array(f.association.foreign_key).map(&:to_sym) })
+        end
+        names
+      end
+    end
+
+    # Mirrors the names the export form offers (main/export.html.erb).
+    def field_names(fields)
+      fields.each_with_object({only: [], methods: []}) do |field, names|
+        list = field.virtual? ? names[:methods] : names[:only]
+        if field.association?
+          list << field.method_name.to_sym << field.association.foreign_type.to_sym
+        else
+          list << field.name.to_sym
+        end
+      end
+    end
+
+    # An empty `only` serializes no attribute in ActiveRecord, which is the point.
+    def filter(requested, permitted)
+      schema = {only: Array(requested[:only]) & permitted[:only]}
+      schema[:methods] = Array(requested[:methods]) & permitted[:methods] if requested.key?(:methods)
+      schema
+    end
+  end
+end

data/lib/rails_admin_next/version.rb

@@ -6,8 +6,8 @@ module RailsAdminNext
     # the tag's version over these constants at build time, so the in-repo values are only
     # the floor a local `gem build` produces.
     MAJOR = 1
-    MINOR = 1
-    PATCH = 2
+    MINOR = 2
+    PATCH = 1
     PRE = nil
 
     class << self

data/lib/rails_admin_next.rb

@@ -12,6 +12,7 @@ require "rails_admin_next/extensions/paper_trail"
 require "rails_admin_next/support/csv_converter"
 require "rails_admin_next/support/hash_helper"
 require "rails_admin_next/support/paginated_collection"
+require "rails_admin_next/support/serialization_schema"
 require "yaml"
 
 module RailsAdminNext

data/skills/rails-admin-next/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rails-admin-next
+description: Configure or extend the rails_admin_next admin in a host Rails app (models, fields, custom actions and field types, CanCanCan/Pundit authorization, PaperTrail history, theming, CSP). Use instead of upstream RailsAdmin knowledge, which is wrong for this fork.
+---
+
+# rails_admin_next
+
+rails_admin_next is a hard fork of RailsAdmin: ActiveRecord only, Rails 8.1, importmap + Propshaft, Turbo + Stimulus, no build step. Most of the per-model DSL is unchanged from upstream, but the namespace, the asset stack and the frontend are not. Code written from upstream RailsAdmin memory is usually wrong here.
+
+## Read the installed gem first
+
+Every `<gem>/` path below is relative to the directory this prints:
+
+```bash
+bundle info --path rails_admin_next
+```
+
+Read the version the app actually bundles before answering:
+
+- `<gem>/docs/UPGRADING.md` lists every difference from upstream RailsAdmin.
+- `<gem>/docs/security.md` covers what the engine enforces and what the host opts into.
+- `<gem>/docs/upstream-parity.md` has a "Standing divergences" section on behavior that deliberately differs from upstream patches.
+- `<gem>/lib/rails_admin_next/config/` is the DSL itself. When this skill and the source disagree, the source wins.
+
+The upstream RailsAdmin wiki is still accurate for model, group and field options that the fork leaves unchanged. Check it against the source above before relying on it.
+
+## Naming: what was renamed, what was not
+
+Renamed (write the new form):
+
+- Ruby namespace `RailsAdminNext`, configured with `RailsAdminNext.config do |config| ... end` in config/initializers/rails_admin_next.rb.
+- Mount: `mount RailsAdminNext::Engine => "/admin", as: "rails_admin_next"`. Keep the `rails_admin_next` alias, because the engine's views call that route proxy.
+- Per-model macro `rails_admin_next do ... end`.
+- Route helpers `rails_admin_next.dashboard_path`, `rails_admin_next_url`, and `bindings[:view].rails_admin_next` inside field blocks.
+
+Not renamed (leave as is):
+
+- The authorization subject is still `:rails_admin`. CanCanCan abilities grant `can :access, :rails_admin`. Never rewrite it to `:rails_admin_next`, which fails authorization.
+- Action authorization keys (`:dashboard`, `:index`, `:show`, `:new`, `:edit`, `:export`, `:destroy`, `:history`, `:show_in_app`).
+- The `admin.*` I18n namespace.
+
+`bin/rails g rails_admin_next:install` writes the initializer and the mount.
+
+## Models, sections and fields
+
+Configure a model either inline with the `rails_admin_next do ... end` macro or in the initializer with `config.model "Team" do ... end`. Both take the upstream DSL: `list`, `show`, `edit`, `create`, `update`, `export`, `nested` and `modal` sections, plus `field`, `configure`, `exclude_fields`, `group` and `navigation_icon`. Global options live on `config`, for example `included_models`, `excluded_models`, `default_items_per_page` and `label_methods`.
+
+Field types live in `<gem>/lib/rails_admin_next/config/fields/types/`. A custom type subclasses one of them and registers with `RailsAdminNext::Config::Fields::Types.register(MyType)`. Register it under a name of your own, or the registration replaces the built-in type.
+
+Read the "Required `belongs_to` associations" and "Nested forms hide the link back to the parent" sections of `<gem>/docs/UPGRADING.md` before changing association fields. Both behave differently from upstream.
+
+## Actions
+
+Pick and order actions in the initializer:
+
+```ruby
+RailsAdminNext.config do |config|
+  config.actions do
+    dashboard
+    index
+    new
+    export
+    bulk_delete
+    show
+    edit
+    delete
+    show_in_app
+  end
+end
+```
+
+A custom action subclasses `RailsAdminNext::Config::Actions::Base`, registers with `RailsAdminNext::Config::Actions.register(self)`, and then appears by name inside `config.actions`. Its options (`member`, `collection`, `http_methods`, `controller`, `link_icon`, `visible?`, `authorization_key`, `template_name` and the rest) are declared in `<gem>/lib/rails_admin_next/config/actions/base.rb`. `<gem>/lib/rails_admin_next/config/actions/show_in_app.rb` is a short example. The action renders the host view app/views/rails_admin_next/main/<template_name>.html.erb.
+
+Icons take logical names, never Font Awesome classes: `link_icon :show_in_app` or `navigation_icon :list`. The list is in the "Icons" section of `<gem>/docs/UPGRADING.md`.
+
+## Authorization and history
+
+- `config.authorize_with :cancancan` uses the app's `Ability`. Keep the `:rails_admin` subject (see Naming).
+- `config.authorize_with :pundit` calls the record's policy with `<action>?` methods (`index?`, `edit?`, `dashboard?`) and scopes lists with `policy_scope`.
+- `config.authorize_with do ... end` runs a custom block as a before filter.
+- `config.authenticate_with do ... end` and `config.current_user_method do ... end` wire in the app's authentication, such as Devise or Warden.
+- `config.audit_with :paper_trail` turns on the history action. Read the "History / audit table" section of `<gem>/docs/UPGRADING.md` first.
+
+## Frontend
+
+- The host app must use Propshaft and importmap-rails. There is no Sprockets, Webpacker, Webpack, Vite or build step, and there is no `config.asset_source` option.
+- The engine runs its own Stimulus application, exposed as `window.RailsAdminNext.application`. Register custom controllers on that instance, not on the host's Stimulus app.
+- Add JavaScript to the admin through a host config/importmap.rails_admin.rb. The engine appends it after its own map, so it can add pins or override the entrypoint pin. The engine's pin names are in `<gem>/config/importmap.rails_admin.rb`.
+- There is no jQuery, jQuery UI, Bootstrap JS or `@rails/ujs`. Confirmations use Turbo's `data-turbo-confirm`.
+- Date and time fields are native HTML5 inputs, with no flatpickr. Rich text is ActionText/Trix. There are no CDN editors such as CKEditor, CodeMirror or froala.
+- The admin supports only the latest Chrome and Safari, so modern CSS and DOM APIs are fair game.
+
+## Theming
+
+Engine CSS sits in the cascade layers `ra.tokens`, `ra.framework` and `ra.skin`, so any unlayered host rule wins without specificity tricks. Rebrand by overriding `--ra-*` tokens, for example `:root { --ra-primary: #663399; }`. Upstream `--bs-*` variables do nothing here. The supported tokens and the `--bs-*` to `--ra-*` mapping are in the "Styling" section of `<gem>/docs/UPGRADING.md`. Dark mode follows the OS. `config.color_scheme = :light` (or `:dark`, or `:auto`) pins it.
+
+## Security
+
+The engine always enforces these, and there is no option to weaken them: CSRF, `X-Frame-Options: SAMEORIGIN`, non-GET export, confirmation on delete, and visible-field slicing of submitted attributes. A Content Security Policy is opt-in through `config.content_security_policy do |policy| ... end`. Pass `report_only: true` while tuning it. Read `<gem>/docs/security.md` before writing the policy. It lists the inline styles that still need `:unsafe_inline` in `style-src`.
+
+## Never suggest
+
+Mongoid, `RailsAdmin.config`, `rails_admin do` blocks, Font Awesome icon classes, jQuery plugins, Sprockets or Webpacker setup, or a migration from upstream RailsAdmin. The migration is a one-time rename, and `<gem>/docs/UPGRADING.md` covers it.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_admin_next
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.1
 platform: ruby
 authors:
 - Daniel López Prat
@@ -189,6 +189,9 @@ files:
 - config/initializers/active_record_extensions.rb
 - config/locales/rails_admin_next.en.yml
 - config/routes.rb
+- docs/UPGRADING.md
+- docs/security.md
+- docs/upstream-parity.md
 - lib/generators/rails_admin_next/install_generator.rb
 - lib/generators/rails_admin_next/templates/initializer.erb
 - lib/generators/rails_admin_next/utils.rb
@@ -295,8 +298,10 @@ files:
 - lib/rails_admin_next/support/csv_converter.rb
 - lib/rails_admin_next/support/hash_helper.rb
 - lib/rails_admin_next/support/paginated_collection.rb
+- lib/rails_admin_next/support/serialization_schema.rb
 - lib/rails_admin_next/version.rb
 - lib/tasks/rails_admin.rake
+- skills/rails-admin-next/SKILL.md
 - src/rails_admin/application.js
 - src/rails_admin/base.js
 - src/rails_admin/controllers/alert_controller.js
@@ -324,6 +329,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/6temes/rails_admin_next/issues
   changelog_uri: https://github.com/6temes/rails_admin_next/releases
+  hyperdrive_targets: rails_admin_next
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/6temes/rails_admin_next
 rdoc_options: []
@@ -333,7 +339,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.5
+      version: 4.0.9
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="