persistence

docs/3.0/customization.md

@@ -591,3 +591,72 @@ Using [searchable](./associations/belongs_to.html#searchable) is recommended for
 
 <Image src="/assets/img/customization/associations-lookup-list-limit.png" width="2466" height="1098" alt="Associations lookup list limit configuration" />
 </Option>
+
+<Option name="`persistence`">
+
+### Persistent UI State Configuration <VersionReq version="3.15.4" />
+
+#### Overview
+
+The `persistence` configuration enables retention of specific UI settings, such as pagination and static filters, across user interactions.
+
+---
+
+#### Configuration
+
+By default, the `:driver` is `nil`, which means no persistence is applied. You can configure the `:driver` for persistence as follows:
+
+```ruby
+Avo.configure do |config|
+  config.persistence = {
+    driver: :session
+  }
+
+  # Or with a dynamic block
+
+  config.persistence = -> do
+    {
+      driver: :session
+    }
+  end
+end
+```
+
+---
+
+#### Behavior
+
+When enabled, the `persistence` configuration ensures the following:
+
+1. **Associations Pagination**
+   The pagination state (e.g., `page` and `per_page` settings) for association tables (e.g., `has_many` fields) is retained across requests.
+
+2. **Static Filters**
+   Static filter selections applied by users are preserved during their session.
+
+---
+
+#### How It Works
+
+Setting `:driver` to `:session` stores the UI state in the user session, enabling it to persist while the session remains active.
+
+---
+
+:::warning
+**Important**:
+To prevent issues with session storage limits, avoid relying solely on the default **cookie store** for session management. The **cookie store** in Rails has a size limit of 4096 bytes. Storing multiple pagination states and filter settings may exceed this limit, resulting in an `ActionDispatch::Cookies::CookieOverflow` error.
+:::
+
+#### Recommended Session Store
+
+To mitigate potential storage overflow, it is advisable to use a more scalable session store, such as:
+
+- **Redis Store**
+- **MemCache Store**
+
+For detailed guidance, refer to the [Rails session store configuration](https://guides.rubyonrails.org/v8.0/configuring.html#config-session-store).
+
+---
+
+By adopting the `persistence` configuration with a suitable session store, you can ensure a seamless user experience.
+</Option>

docs/3.0/upgrade.md

@@ -3,6 +3,41 @@
 We'll update this page when we release new Avo 3 versions.
 
 If you're looking for the Avo 2 to Avo 3 upgrade guide, please visit [the dedicated page](./avo-2-avo-3-upgrade).
+## Upgrade from 3.15.3 to 3.15.4
+
+The `config.cache_resource_filters` option is now **obsolete** and has been replaced with `config.persistence`. If you previously had:
+
+```ruby
+config.cache_resource_filters = true
+```
+
+You should update your configuration to:
+
+```ruby
+config.persistence = { driver: :session }
+```
+
+This updated setting preserves the same behavior, ensuring resource filters and association pagination states persist across requests for a consistent user experience. For additional details, refer to the [`persistence` documentation](./customization.html#persistence).
+
+---
+
+### Persistent Pagination Behavior
+
+By default, pagination settings for associations are no longer stored in the session. If your application requires persistent pagination, you must explicitly enable the `persistence` configuration:
+
+```ruby
+Avo.configure do |config|
+  config.persistence = { driver: :session }
+end
+```
+
+---
+
+:::warning
+**Important**:
+When enabling this feature, it is strongly recommended to **update the session store** to avoid potential cookie overflow errors. The default Rails **cookie store** has a size limit of 4096 bytes, and persisting multiple pagination states or filters can exceed this limit. For more information, refer to the [`persistence` configuration documentation](./customization.html#persistence).
+:::
+
 ## Upgrade from 3.14.0 to 3.14.1
 
 We’ve introduced the [`associations_lookup_list_limit`](customization.html#associations_lookup_list_limit) configuration option to prevent crashing when listing associations on large collections. The new default limit is set to a `1000` records.