wor-simple_crud 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f3a2ed3cb6cea9416a6a745959519ccfdd9fd3a35667432939ece4291368266
-  data.tar.gz: 6b0625c10d66661cff9b09959ddd7f1a0eae630c0a519fa34116855b38588377
+  metadata.gz: 667672176b1c817bdcf1d9c5248e1b3701253d52f289a85bc2e4b3e632c47188
+  data.tar.gz: f03748bda6004b670a8989fed13d82e0c6e0e0ec6bd9323a1c4e43e786da4dfe
 SHA512:
-  metadata.gz: c4b2ab3b62121f5409a0d11d498a094162f847027941deb4abb3c72dc0c5c623934c3aeee5a65c64149039fbf2c09d4e9f9a8e10da6818ad32e236545e592331
-  data.tar.gz: 75211a88220e4328897ba0c36ebd55b04742bc253874f711cf14e644ff5a9d595455003facfb7ad9896346e63570d6dffb36fbeb947e34261a17e38ddb60aa80
+  metadata.gz: '04257318d37af96ef5df3d17d2561dfad551cf3eaca51dc4630d7e7d9a7d19cd05852a4b31e00902ab245610d0e35379e3314586f18646afe3ddb246a17a1756'
+  data.tar.gz: 81b0fda087fc2723f8f7a6789f7f2542037b7054b36e9db8aed05eba03f5cdbcb0c38fdf45da85f60e9b3e67c58332118d73be257e5d16b108559eade35adba7

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 ## Change log
 
+### V0.3.0
+
+Server-rendered (HTML) support:
+* `html: true` or a render block on every action: `:index` renders `index.html.erb` with the paginated records as `@records`; `:show`/`:new` expose `@record`; `:create`/`:update` redirect to the record on success and re-render the form with errors on failure; `:destroy` redirects to the collection (re-rendering `show.html.erb` when a callback aborts). Blocks receive the records (`:index`), the record (`:show`/`:new`) or `(record, saved)` (`:create`/`:update`/`:destroy`) and override the auto-render.
+* New `:new` action: builds a record, authorizes it, and renders `new.html.erb` (or returns JSON in API mode).
+
+Custom lookups, scoping and building:
+* `finder:` on `:show`/`:update`/`:destroy`: a `Proc`/lambda invoked with the controller's params, or a `Symbol` naming a class method on the model. Defaults to `klass.find(params[:id])`.
+* `build:` on `:new`/`:create` for owner-scoped or nested builds (`current_user.classrooms.build`); runs with the controller as `self`, and `:create` assigns the permitted params to the built record before saving.
+* With `authorize: true`, `:index` paginates the Pundit `policy_scope` of the model (falling back to the full relation when no `Scope` is defined) instead of `klass.all`, with a per-action `scope: ->(user[, params]) { ... }` override.
+* `redirect:` on HTML-mode `:create`/`:update`/`:destroy`: a `Proc` called with the record, or a literal path, overriding the default success redirect.
+
+Validation errors:
+* `:create` returns `201` / `422 { errors: [...] }` and `:update` returns `200` / `422` instead of raising; `raise_on_invalid: true` keeps strict `create!`/`update!` semantics.
+
+Authorization changes:
+* Breaking: `authorize: true` now always enforces policy checks, including for `authenticate: false` actions, which reach policies with a `nil` user. Policies must tolerate a `nil` user.
+* `SimpleCrud::Config.user_method` (default `:current_user`) selects the controller method providing the user to policies and scope lambdas, so apps with other conventions (`current_admin`, ...) need no shims.
+
+Adapter interfaces:
+* Authorization adapters gain `policy_scope`; pagination adapters gain `paginated_records`, so HTML-mode `:index` can fetch the current page without rendering. Both are implemented by every shipped adapter (Pundit, CanCanCan, Action Policy / wor-paginate, Kaminari, will_paginate, Pagy).
+
+Fixes:
+* Kaminari adapter: string query params corrupted offsets (`?page=3&per_page=10` resolved to `OFFSET 1010`), and `per_page` now respects `Kaminari.config.max_per_page`.
+* Custom finders returning anything but a single record raise `ActiveRecord::RecordNotFound` instead of failing later with an obscure error.
+* Invalid `simple_crud_for` usage (unknown action, missing policy, missing serializer) raises `ArgumentError` instead of throwing uncatchable string tags.
+
+Testing library:
+* The shared examples are a reusable library: configure via `SimpleCrud::RSpec.configure`, wire up explicitly with `SimpleCrud::RSpec.install!`. Every app-specific assumption has an overridable default matching the gem's own stack (Devise-JWT + FactoryBot + Pundit + AMS): `authenticate`/`current_user`/`other_user`, `create_record`/`create_records`/`params_for`, `owner_association`/`required_attribute`/`required_error`, `finder_key`, `params_key`, `route_params`, `invalid_status`, `unauthenticated_status`, `assert_html_template`, `policy_class`, `serializer_class`.
+* Examples are HTML-aware (branching on the `html:` option, inferring it for block-form actions) and issue requests by action name, so one set covers API and server-rendered controllers, namespaced and nested routes alike.
+* Refactor `SimpleCrudController` helpers into `SimpleCrud::ControllerHelpers`, dedupe repeated test code, and require `rails-controller-testing` for template assertions. Tested across Rails 6.1-8.1.
+
 ### V0.2.1
 * Rename the published gem from `simple_crud` to `wor-simple_crud`. `simple_crud` is already taken on RubyGems by an unrelated gem, and RubyGems also rejects names that differ from an existing one only by hyphen/underscore (so `simple-crud` was rejected too). Install with `gem 'wor-simple_crud', require: 'simple_crud'` (the require path is unchanged).
 * Drop the last Wolox references now that this gem lives at icoluccio/simple-crud, and point the wor-paginate link and CI/gem badges at their new homes.

data/Gemfile

@@ -28,6 +28,7 @@ group :development, :test do
   gem 'overcommit', '~> 0.72'
   gem 'pagy', '~> 43.0', require: false
   gem 'pundit', '~> 2.5'
+  gem 'rails-controller-testing', '~> 1.0'
   gem 'rake', '~> 13.4'
   gem 'rspec', '~> 3.13'
   gem 'rspec-rails', '>= 6.0', '< 9'

data/README.md

@@ -14,7 +14,10 @@ SimpleCrud
       - [Options](#options)
         - [Paginate](#paginate)
         - [Authorize](#authorize)
+        - [Authenticate](#authenticate)
         - [Serializer](#serializer)
+        - [HTML](#html)
+        - [Finder](#finder)
       - [Shared examples](#shared-examples)
   - [Contributing](#contributing)
   - [Releases](#releases)
@@ -64,7 +67,7 @@ Before SimpleCrud can be used, some boilerplate is needed. Add the following to
 ```ruby
 include Pundit::Authorization
 include Wor::Paginate
-extend SimpleCrud
+extend SimpleCrudController
 
 before_action :set_params
 
@@ -91,6 +94,7 @@ simple_crud_for :show
 simple_crud_for :index
 simple_crud_for :create
 simple_crud_for :destroy
+simple_crud_for :new
 ```
 
 Each method supports different options, as in:
@@ -102,6 +106,12 @@ simple_crud_for :index, paginate: false, authorize: false, serializer: CustomSer
 - Authorize: whether it should check authorization via the configured authorization adapter (Pundit by default)
 - Authenticate: whether it should use Devise to check for a current_user
 - Serializer: specify a particular serializer you should use
+- Html: renders the action's ERB template instead of JSON (valid for `:index`, `:show`, `:new`, `:create`, `:update` and `:destroy`). Only meaningful in controllers that render templates
+- Scope: only valid for `:index`. A `Proc`/`lambda` taking `current_user` (plus the controller's `params` if it takes a second argument) that returns the relation to list, overriding the default `policy_scope`. The user is resolved via `SimpleCrud::Config.user_method` (`:current_user` by default; set it to e.g. `:current_admin`)
+- Finder: only valid for `:show`, `:update` and `:destroy`. A `Proc`/`lambda` (invoked with the controller's params) or a `Symbol` naming a class method on the model, used to look up the record instead of `klass.find(params[:id])`.
+- Build: only valid for `:new` and `:create`. A `Proc`/`lambda` that builds the record (invoked with the controller as `self`, so `current_user`, `params` and any instance variables are available), for building nested or owner-scoped records like `current_user.classrooms.build`. `:create` then assigns the permitted params to the built record before saving
+- Raise_on_invalid: only valid for `:create` and `:update`. Keeps the strict `create!`/`update!` semantics (raising on invalid input) instead of returning `422` with the validation errors
+- Redirect: only valid for HTML-mode `:create`, `:update` and `:destroy`. A `Proc`/`lambda` (called with the record) or a literal path used as the success redirect target. Defaults to the record (`:create`/`:update`) or the model's collection path (`:destroy`)
 
 You'll need a few things so they work correctly:
 
@@ -143,10 +153,11 @@ end
 
 SimpleCrud.configure { |config| config.pagination_adapter = MyPaginationAdapter.new }
 ```
-
 #### Authorize
 Authorization checks go through [Pundit](https://github.com/varvet/pundit) by default. Name the policy after the model plus `Policy`, e.g. `AuthorPolicy`, written as a regular Pundit policy:
 
+> **Note:** authorization runs whenever `authorize: true`, independently of `authenticate`. With no signed-in user the policy receives `nil` as the user, so write policies that tolerate it (e.g. `user.nil? ? false : ...`). Devise provides `authenticate_user!` and `current_user` for you; non-Devise apps must define a `current_user` (or point `SimpleCrud::Config.user_method` at their own method) for policies and `scope:` lambdas to receive the user.
+
 ```ruby
 class AuthorPolicy
   attr_reader :user, :author
@@ -159,10 +170,30 @@ class AuthorPolicy
   def show?
     user.present?
   end
+
+  class Scope
+    def initialize(user, scope)
+      @user = user
+      @scope = scope
+    end
+
+    # Used by :index to scope the listed records to the current user.
+    def resolve
+      @scope.where(user: @user)
+    end
+  end
 end
 
 ```
 
+When `authorize: true`, the `:index` action paginates the Pundit `policy_scope` of the model (falling back to the full relation when no `Scope` is defined) instead of `klass.all`, so "only my records" scoping works out of the box. Override the scope per action with the `scope:` option, a callable that receives the user resolved via `SimpleCrud::Config.user_method` (`nil` when there is none, and `params` too when it takes a second argument):
+
+```ruby
+SimpleCrud.configure { |c| c.user_method = :current_admin } # non-Devise naming conventions
+simple_crud_for :index, scope: ->(user) { Model.visible_to(user) }
+simple_crud_for :index, scope: ->(user, params) { Model.where(status: params[:status]).visible_to(user) }
+```
+
 Prefer CanCanCan or Action Policy instead? Both have adapters ready to go:
 
 ```ruby
@@ -200,6 +231,13 @@ class MyAuthorizationAdapter
   def policy_defined?(model_class)
     Kernel.const_defined?("#{model_class}Policy")
   end
+
+  # Called when rendering :index with authorize: true. Must return the
+  # relation the current user is allowed to list. The default returns
+  # the full relation.
+  def policy_scope(controller, model_class)
+    model_class.all
+  end
 end
 
 SimpleCrud.configure do |config|
@@ -219,6 +257,58 @@ class AuthorSerializer < ActiveModel::Serializer
 end
 ```
 
+#### HTML
+For server-rendered apps, `html: true` renders the action's ERB template instead of JSON, so be sure the controller can render templates (e.g. `ActionController::Base`). Behavior per action:
+
+- `:index` renders `index.html.erb` with the paginated records exposed as `@records` (pagination still applies, or use `paginate: false`).
+- `:show` renders `show.html.erb` with the record exposed as `@record` (custom `finder:` still applies).
+- `:new` builds a new record, authorizes it, and renders `new.html.erb` with it exposed as `@record`.
+- `:create` saves and redirects to the created record on success, or re-renders `new.html.erb` (with `@record` and its errors) on failure.
+- `:update` saves and redirects to the record on success, or re-renders `edit.html.erb` on failure.
+- `:destroy` destroys and redirects to the collection (`redirect_to Model`) on success, or re-renders `show.html.erb` if a callback aborts the destroy.
+
+```ruby
+simple_crud_for :index, html: true
+simple_crud_for :show, html: true
+simple_crud_for :new, html: true
+simple_crud_for :create, html: true
+simple_crud_for :update, html: true
+simple_crud_for :destroy, html: true
+```
+
+Or pass a block that renders explicitly, overriding the auto-render. The block receives the records for `:index`, the record for `:show`/`:new`, or the record plus a saved flag for `:create`/`:update`/`:destroy`. Passing a block also implies `html: true` for the shared examples (so a server-rendered block is asserted as HTML); if your block renders JSON instead, pass `html: false` explicitly:
+
+```ruby
+simple_crud_for :index do |records|
+  render :index, locals: { models: records }
+end
+
+simple_crud_for :create do |record, saved|
+  saved ? redirect_to(record) : render(:new, locals: { model: record })
+end
+```
+
+#### Build
+`simple_crud_for :new` and `simple_crud_for :create` build the record with `klass.new`, which can't express owner-scoped or nested records (`current_user.classrooms.build`, `@classroom.assignments.build`). Pass a `build:` lambda; it runs with the controller as `self`, so `current_user`, `params` and any instance variables set by a `before_action` are available:
+
+```ruby
+simple_crud_for :new, build: -> { current_user.classrooms.build }
+simple_crud_for :create, build: -> { current_user.classrooms.build }
+```
+
+`:create` assigns the permitted params to the built record before saving, so the owner/parent association survives. `:update` keeps finding the record via the `finder:`.
+
+#### Finder
+By default records are looked up by primary key via `klass.find(params[:id])`. The `finder:` option on `:show`, `:update` and `:destroy` replaces that with any lookup you want: pretty URLs (`resources :posts, param: :slug`), tokens, composite keys, or scoping by a parent resource. Pass a `Proc`/`lambda` that maps the controller's `params` to a record, or a `Symbol` naming a class method on the model that takes the params:
+
+```ruby
+simple_crud_for :show, finder: ->(params) { Model.find_by!(token: params[:token]) }
+simple_crud_for :update, finder: :find_by_slug
+simple_crud_for :destroy, finder: ->(params) { current_user.models.find(params[:id]) }
+```
+
+When omitted it defaults to `klass.find(params[:id])`, and `not_found` is still returned whenever the finder finds no record.
+
 ### Shared examples
 While optional, using the included shared examples saves you from writing the standard test cases for the methods. You can even use them if you didn't use `simple_crud_for`, as a set of basic tests. To include them, just add `require 'simple_crud/rspec'` to your `rails_helper.rb` file and add the lines you need to your `*_spec.rb` files:
 ```ruby
@@ -233,8 +323,73 @@ describe V1::Backoffice::AuthorsController do
 end
 ```
 
+The `create` and `update` examples cover the `422` response with validation errors (skipped when `raise_on_invalid: true`), and all base examples adapt to `html: true` controllers (asserting the rendered template/redirect instead of JSON). Controllers using the extra options can include their dedicated examples too:
+
+```ruby
+include_examples 'simple crud for new'                    # the :new action
+include_examples 'simple crud for index with block'      # render block
+include_examples 'simple crud for index with scope'      # scope: ->(user) { ... }
+include_examples 'simple crud for show with block'       # render block on :show
+include_examples 'simple crud for new with block'        # render block on :new
+include_examples 'simple crud for create with block'     # render block on :create
+include_examples 'simple crud for destroy with block'    # render block on :destroy
+include_examples 'simple crud for show with finder'      # finder on :show
+include_examples 'simple crud for update with finder'    # finder on :update
+include_examples 'simple crud for destroy with finder'   # finder on :destroy
+include_examples 'simple crud for new with build'        # build: -> { ... } on :new
+include_examples 'simple crud for create with build'     # build: -> { ... } on :create
+```
+
 It's not needed to specify paginate: true and such, since the shared examples will use the configuration that was originally passed to simple_crud_for
 
+#### Adopting the shared examples
+The shared examples assume the gem's own stack by default (Devise-JWT authentication, FactoryBot, Pundit, ActiveModel Serializers). Wiring is opt-in: require the file and call `SimpleCrud::RSpec.install!` in `spec/spec_helper.rb` (or `rails_helper.rb`), then configure anything your app differs on:
+
+```ruby
+SimpleCrud::RSpec.configure do |config|
+  # How the current user (and a secondary "other user") is built.
+  config.current_user = -> { User.create!(email: 'user@example.com', password: 'secret') }
+  config.other_user = -> { User.create!(email: 'other@example.com', password: 'secret') }
+
+  # How to sign the current user in for a request (no Devise-JWT here).
+  config.authenticate = -> { request.session[:user_id] = current_user.id }
+
+  # How records and create/update params are built (no FactoryBot here).
+  config.create_record = ->(klass, attributes) { klass.create!(attributes) }
+  config.create_records = ->(klass, count, attributes) { count.times.map { klass.create!(attributes) } }
+  config.params_for = ->(klass) { klass.new.attributes.slice('title') }
+
+  # The owner association and the validation this app's models enforce.
+  config.owner_association = :instructor
+  config.required_attribute = :title
+  config.required_error = "Title can't be blank"
+
+  # Redirect-based apps: unauthenticated requests get a redirect, not a 401.
+  # And if the rendered template name doesn't match the action, drop the
+  # render_template assertion.
+  config.unauthenticated_status = :found
+  config.assert_html_template = false
+
+  # Server-rendered apps usually use nested strong params
+  # (params.require(:classroom).permit(:name)); wrap request bodies under the
+  # model's params key instead of posting flat params.
+  config.params_key = :classroom
+
+  # Nested resources (/classrooms/:classroom_slug/assignments): extra params
+  # (e.g. the parent slug) added to every request.
+  config.route_params = -> { { classroom_slug: model.classroom_slug } }
+
+  # Re-render the form with a 422 on validation failure (instead of 200).
+  config.invalid_status = :unprocessable_entity
+
+  # Pundit policy and serializer class lookup.
+  config.policy_class = ->(klass) { "#{klass}Policy".constantize }
+  config.serializer_class = ->(model) { "#{model.class}Serializer".constantize }
+end
+```
+
+Each setting has a sensible default, so you only override what differs. Callable settings (`current_user`, `authenticate`, `create_record`, `create_records`, `params_for`, `policy_class`, `serializer_class`) run in the example-group context, so they can call `request`, `create`, `current_user`, etc. The examples are controller-agnostic (they issue requests by action name, not hardcoded paths), so they work for namespaced and nested controllers alike. If you keep `assert_html_template` on (the default), add `gem 'rails-controller-testing'` for the `render_template` matcher.
+
 ## Contributing
 
 1. Fork it

data/lib/simple_crud/authorization/adapter.rb

@@ -15,6 +15,13 @@ module SimpleCrud
       def policy_defined?(model_class)
         raise NotImplementedError
       end
+
+      # Called when rendering :index with authorize: true. Must return the
+      # relation the current user is allowed to list. Defaults to the full
+      # relation so no scoping dependency is required.
+      def policy_scope(_controller, model_class)
+        model_class.all
+      end
     end
   end
 end

data/lib/simple_crud/authorization/pundit_adapter.rb

@@ -16,6 +16,12 @@ module SimpleCrud
       def policy_defined?(model_class)
         Kernel.const_defined?("#{model_class}Policy")
       end
+
+      def policy_scope(controller, model_class)
+        controller.send(:policy_scope, model_class)
+      rescue Pundit::NotDefinedError
+        model_class.all
+      end
     end
   end
 end

data/lib/simple_crud/config.rb

@@ -4,7 +4,7 @@ module SimpleCrud
   # Holds simple_crud's configurable pieces, set via SimpleCrud.configure.
   class Config
     class << self
-      attr_writer :authorization_adapter, :pagination_adapter
+      attr_writer :authorization_adapter, :pagination_adapter, :user_method
 
       def authorization_adapter
         @authorization_adapter ||= begin
@@ -19,6 +19,11 @@ module SimpleCrud
           Pagination::WorPaginateAdapter.new
         end
       end
+
+      # Controller method providing the current user; override for non-Devise apps.
+      def user_method
+        @user_method ||= :current_user
+      end
     end
   end
 end

data/lib/simple_crud/controller_helpers.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  # Class-level helpers shared by the CRUD lambdas defined in SimpleCrudController.
+  module ControllerHelpers
+    def maybe_authorize(controller, record, parameters)
+      return unless parameters[:authorize]
+
+      SimpleCrud::Config.authorization_adapter.authorize(controller, record)
+    end
+
+    def render_index(controller, klass, options, parameters, &block)
+      relation = index_relation(controller, klass, parameters)
+
+      if parameters[:html] || block
+        records = index_records(controller, relation, options, parameters)
+        controller.instance_variable_set(:@records, records)
+        block ? controller.instance_exec(records, &block) : controller.render(:index)
+      elsif parameters[:paginate]
+        SimpleCrud::Config.pagination_adapter.paginate(controller, relation, options)
+      else
+        controller.render({ json: relation }.merge(options))
+      end
+    end
+
+    def render_show(controller, record, options, parameters, &block)
+      if parameters[:html] || block
+        controller.instance_variable_set(:@record, record)
+        block ? controller.instance_exec(record, &block) : controller.render(:show)
+      else
+        controller.render({ json: record }.merge(options))
+      end
+    end
+
+    def render_new(controller, record, parameters, &block)
+      if parameters[:html] || block
+        controller.instance_variable_set(:@record, record)
+        block ? controller.instance_exec(record, &block) : controller.render(:new)
+      else
+        controller.render json: record
+      end
+    end
+
+    def build_record(controller, klass, parameters)
+      parameters[:build] ? controller.instance_exec(&parameters[:build]) : klass.new
+    end
+
+    def index_relation(controller, klass, parameters)
+      if parameters[:scope]
+        call_scope(parameters[:scope], controller)
+      elsif parameters[:authorize]
+        SimpleCrud::Config.authorization_adapter.policy_scope(controller, klass)
+      else
+        klass.all
+      end
+    end
+
+    def call_scope(scope, controller)
+      user_method = SimpleCrud::Config.user_method
+      user = controller.respond_to?(user_method) ? controller.public_send(user_method) : nil
+      return scope.call(user) if scope.arity == 1
+
+      scope.call(user, controller.params)
+    end
+
+    def index_records(controller, relation, options, parameters)
+      return relation unless parameters[:paginate]
+
+      SimpleCrud::Config.pagination_adapter.paginated_records(controller, relation, options)
+    end
+
+    def find_record(klass, controller, parameters)
+      record = lookup_record(klass, controller, parameters)
+      raise ActiveRecord::RecordNotFound, "couldn't find #{klass}" if record.nil?
+      unless record.is_a?(ActiveRecord::Base)
+        raise ActiveRecord::RecordNotFound, "#{klass} finder must return a single record"
+      end
+
+      record
+    end
+
+    def lookup_record(klass, controller, parameters)
+      finder = parameters[:finder]
+      return klass.find(controller.params[:id]) if finder.nil?
+      return klass.send(finder, controller.params) unless finder.respond_to?(:call)
+
+      finder.call(controller.params)
+    end
+
+    def persist_and_render(controller, record, parameters, options, persist, &block)
+      saved = parameters[:raise_on_invalid] ? persist.call(bang: true) : persist.call(bang: false)
+      return render_persisted(controller, record, saved, options) unless block || parameters[:html]
+
+      controller.instance_variable_set(:@record, record)
+      return controller.instance_exec(record, saved, &block) if block
+
+      if saved
+        controller.redirect_to(redirect_target(controller, record, options[:redirect]))
+      else
+        controller.render(options[:failure_template])
+      end
+    end
+
+    def save_and_render(controller, record, parameters, options, persist, &block)
+      persist_and_render(controller, record, parameters,
+                         options.merge(redirect: parameters[:redirect] || record), persist, &block)
+    end
+
+    def redirect_target(controller, record, target)
+      target.is_a?(Proc) ? controller.instance_exec(record, &target) : target
+    end
+
+    def render_persisted(controller, record, saved, options)
+      return controller.render(json: record, status: options[:status]) if saved
+
+      controller.render json: { errors: record.errors.full_messages }, status: 422
+    end
+  end
+end

data/lib/simple_crud/pagination/adapter.rb

@@ -6,7 +6,13 @@ module SimpleCrud
     # (the default, see WorPaginateAdapter).
     module Adapter
       # Called when paginate: true. Must render the response itself.
-      def paginate(controller, klass, options)
+      def paginate(controller, relation, options)
+        raise NotImplementedError
+      end
+
+      # Called when rendering :index as HTML (html: true or a block given) and
+      # paginate: true. Must return the current page's records without rendering.
+      def paginated_records(controller, relation, options)
         raise NotImplementedError
       end
     end

data/lib/simple_crud/pagination/kaminari_adapter.rb

@@ -10,10 +10,31 @@ module SimpleCrud
     class KaminariAdapter
       include Adapter
 
-      def paginate(controller, klass, options)
-        records = klass.page(controller.params[:page]).per(controller.params[:per_page])
+      def paginate(controller, relation, options)
+        records = paginated_records(controller, relation, options)
         controller.render({ json: records }.merge(options))
       end
+
+      # Manual page scope: will_paginate shadows Relation#page when both load.
+      def paginated_records(controller, relation, _options)
+        page = [controller.params[:page].to_i, 1].max
+        per_page = page_size(controller)
+
+        relation.limit(per_page).offset(per_page * (page - 1)).extending do
+          include Kaminari::ActiveRecordRelationMethods
+          include Kaminari::PageScopeMethods
+        end
+      end
+
+      private
+
+      # Params arrive as strings: coerce before arithmetic or "5" * 2 == "55".
+      def page_size(controller)
+        size = (controller.params[:per_page] || Kaminari.config.default_per_page).to_i
+        size = [size, 1].max
+        size = [size, Kaminari.config.max_per_page].min if Kaminari.config.max_per_page
+        size
+      end
     end
   end
 end

data/lib/simple_crud/pagination/pagy_adapter.rb

@@ -13,10 +13,15 @@ module SimpleCrud
       # the pre-rename 43.4.x, so pick whichever key the loaded Pagy expects.
       MAX_LIMIT_KEY = Gem::Version.new(Pagy::VERSION) >= Gem::Version.new('43.5.0') ? :max_limit : :client_max_limit
 
-      def paginate(controller, klass, options)
-        _pagy, records = controller.send(:pagy, klass.all, MAX_LIMIT_KEY => 100)
+      def paginate(controller, relation, options)
+        records = paginated_records(controller, relation, options)
         controller.render({ json: records }.merge(options))
       end
+
+      def paginated_records(controller, relation, _options)
+        _pagy, records = controller.send(:pagy, relation, MAX_LIMIT_KEY => 100)
+        records
+      end
     end
   end
 end

data/lib/simple_crud/pagination/will_paginate_adapter.rb

@@ -11,11 +11,15 @@ module SimpleCrud
     class WillPaginateAdapter
       include Adapter
 
-      def paginate(controller, klass, options)
+      def paginate(controller, relation, options)
+        records = paginated_records(controller, relation, options)
+        controller.render({ json: records }.merge(options))
+      end
+
+      def paginated_records(controller, relation, _options)
         page = controller.params[:page] || 1
         per_page = controller.params[:per_page] || WillPaginate.per_page
-        records = klass.paginate(page: page, per_page: per_page)
-        controller.render({ json: records }.merge(options))
+        relation.paginate(page: page, per_page: per_page)
       end
     end
   end

data/lib/simple_crud/pagination/wor_paginate_adapter.rb

@@ -9,8 +9,13 @@ module SimpleCrud
     class WorPaginateAdapter
       include Adapter
 
-      def paginate(controller, klass, options)
-        controller.send(:render_paginated, klass, options)
+      def paginate(controller, relation, options)
+        controller.send(:render_paginated, relation, options)
+      end
+
+      def paginated_records(controller, relation, options)
+        adapter = controller.send(:find_adapter_for_content, relation, options)
+        adapter.paginated_content
       end
     end
   end

data/lib/simple_crud/rspec/config.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  # Test helpers: SimpleCrud::RSpec.configure exposes the shared examples'
+  # configuration for apps on a different stack than the gem's.
+  module RSpec
+    def self.configure
+      yield Config.instance
+    end
+
+    # Configures how the shared examples create records, authenticate
+    # requests and introspect policies/serializers. The defaults match the
+    # gem's own stack (Devise-JWT + FactoryBot + Pundit + ActiveModel
+    # Serializers), so apps on a different stack can override them via
+    # SimpleCrud::RSpec.configure instead of editing the examples.
+    #
+    # Callable settings (authenticate, current_user, create_record,
+    # create_records, attributes_for, policy_class, serializer_class) run in
+    # the example-group context, so they can call helpers such as `create`,
+    # `request` and `current_user`.
+    class Config
+      DEFAULTS = {
+        authenticate: lambda {
+          headers = { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }
+          request.headers.merge!(Devise::JWT::TestHelpers.auth_headers(headers, current_user))
+        },
+        current_user: -> { create(:user) },
+        other_user: -> { create(:user) },
+        create_record: ->(klass, attributes) { create(klass, **attributes) },
+        create_records: ->(klass, count, attributes) { create_list(klass, count, **attributes) },
+        params_for: ->(klass) { attributes_for(klass) },
+        owner_association: :user,
+        required_attribute: :name,
+        required_error: "Name can't be blank",
+        finder_key: :slug,
+        params_key: nil,
+        route_params: -> { {} },
+        invalid_status: :ok,
+        unauthenticated_status: :unauthorized,
+        assert_html_template: true,
+        policy_class: ->(klass) { "#{klass}Policy".constantize },
+        serializer_class: ->(model) { "#{model.class}_serializer".classify.constantize }
+      }.freeze
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      DEFAULTS.each_key do |key|
+        define_method(key) { @values.fetch(key, DEFAULTS[key]) }
+        define_method("#{key}=") { |value| @values[key] = value }
+      end
+    end
+  end
+end