active_fields 2.0.1 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c94bb84092249c9db341f69ec79233da8440b8ef74c00475c5c8acb6e42a290
-  data.tar.gz: 7653a7859137a53d465ccc2398f055f064105949f0a3be7e1e7fc5f3636ee240
+  metadata.gz: 86d3c04e24cae1b29e2f3a4957cec89fe64132c6b3d7f5432f16c6a84a0d8914
+  data.tar.gz: d1b6d2385b47913edf57ca4709e73eaf04f64f7d6d87a3c5e028b092f3b1a97e
 SHA512:
-  metadata.gz: 57eecfc4cb3cf040dfcc2daf59a804b33ea5b3f9744cde6931c8fa0f9777eeeb067d3895b33ebbf927c5b74c66290f00546986d472d038c11df700d8092631d7
-  data.tar.gz: 1e923ede58bd193079334b3fcb9e193fdd61b56d6d73ffdf977a626618d2e308787641c8194ebc806113141b9dd66a3e5fbea106c0d0ded699c866a10a6b8d0b
+  metadata.gz: abca69b126eacb5fc015d29fc0b7b67bc39e0905c68b8fb1a1fe86a80065838c80a5650fea5beac4bafdee1d123287aad405566115a58e2f0b39fa2c23fe33d5
+  data.tar.gz: f3e0e310b0a1a33f11c3226e2e678fe84bd6787609c189afe6e086b7e039b0852b13df0fcdf08759e06dc1ccf931ba8b9eeff00137faae843a26b02267f77954

data/.rubocop.yml

@@ -3,17 +3,24 @@ plugins:
   - rubocop-rails
   - rubocop-rake
   - rubocop-rspec
+  - rubocop-factory_bot
+  - rubocop-rspec_rails
 
 inherit_gem:
   rubocop-shopify: rubocop.yml
 
 AllCops:
-  TargetRubyVersion: 3.3
-  TargetRailsVersion: 8.0
+  TargetRubyVersion: 3.4
+  TargetRailsVersion: 8.1
   NewCops: enable
   Exclude:
+    - "gemfiles/*"
     - "spec/dummy/db/schema.rb"
 
+Layout/LineLength:
+  Enabled: true
+  Max: 120
+
 Layout/EmptyLinesAroundAccessModifier:
   EnforcedStyle: around
 
@@ -47,3 +54,9 @@ RSpec/ContextWording:
 
 RSpec/MultipleExpectations:
   Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/InclusiveLanguage:
+  Enabled: false

data/Appraisals

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# See https://github.com/thoughtbot/appraisal for more information.
+
+appraise "rails_7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails_7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+appraise "rails_8.0" do
+  gem "rails", "~> 8.0.0"
+end
+
+appraise "rails_8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 ## [Unreleased]
 
-# [2.0.1] - 2025-04-09
+## [3.0.1] - 2025-11-28
+- Fixed an issue where searching with `v: false` was treated as `nil` due to `false || nil` logic
+
+## [3.0.0] - 2025-11-27
+- Disabled fields name format validation
+- Added scope functionality: _Active Field_ can now be limited to a specific context, allowing different sets of fields per group within the same _Customizable_ model.
+- Added Appraisal to run tests across multiple Rails versions.
+
+## [2.0.1] - 2025-04-09
 - Fixed search with `nil` operator
 
 ## [2.0.0] - 2025-02-22

data/README.md

@@ -5,7 +5,38 @@
 [![Github Actions CI](https://github.com/lassoid/active_fields/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/lassoid/active_fields/actions/workflows/main.yml)
 
 **ActiveFields** is a _Rails_ plugin that implements the _Entity-Attribute-Value_ (_EAV_) pattern,
-enabling the addition of custom fields to any model at runtime without requiring changes to the database schema.
+enabling the addition of custom fields to any model at runtime without requiring changes to the database schema or application code.
+
+It may look similar to other gems like [attr_json](https://github.com/jrochkind/attr_json) or [store_attribute](https://github.com/palkan/store_attribute), but it solves a fundamentally different problem. While those tools allow you to add fields without migrations, they still require developer work - you must write code to define each field.
+
+The main use case of _EAV_ in general, and _ActiveFields_ in particular, is to enable **any application user** (not just developers) to add their own fields. Not just without migrations, but without touching the source code at all. These are truly data-driven fields that can be created, modified, and managed entirely through your application's interface.
+
+## Table of Contents
+
+- [Key Concepts](#key-concepts)
+- [Models Structure](#models-structure)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Field Types](#field-types)
+  - [Fields Base Attributes](#fields-base-attributes)
+  - [Field Types Summary](#field-types-summary)
+  - [Search Functionality](#search-functionality)
+- [Configuration](#configuration)
+  - [Limiting Field Types for a Customizable](#limiting-field-types-for-a-customizable)
+  - [Customizing Internal Model Classes](#customizing-internal-model-classes)
+  - [Adding Custom Field Types](#adding-custom-field-types)
+  - [Multi-tenancy (scoping)](#multi-tenancy-scoping)
+  - [Localization (I18n)](#localization-i18n)
+- [Current Restrictions](#current-restrictions)
+- [API Overview](#api-overview)
+  - [Fields API](#fields-api)
+  - [Values API](#values-api)
+  - [Customizable API](#customizable-api)
+  - [Global Config](#global-config)
+  - [Registry](#registry)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Key Concepts
 
@@ -38,6 +69,12 @@ classDiagram
 All values are stored in a JSON (jsonb) field, which is a highly flexible column type capable of storing various data types,
 such as booleans, strings, numbers, arrays, etc.
 
+## Requirements
+
+- Ruby 3.1+
+- Rails 7.1+
+- Postgres 15+ (17+ for search functionality)
+
 ## Installation
 
 1. Install the gem and add it to your application's Gemfile by running:
@@ -286,6 +323,9 @@ classDiagram
 All _Active Field_ model names start with `ActiveFields::Field`.
 We replace it with `**` for conciseness.
 
+<details>
+<summary><strong>Table</strong></summary>
+
 | Active Field model              | Type name        | Attributes                               | Options                                                                                                                                                                                                                                                                                                         |
 |---------------------------------|------------------|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `**::Boolean`                   | `boolean`        | `default_value`<br>(`boolean` or `nil`)  | `required`(`boolean`) - the value must not be `false`<br>`nullable`(`boolean`) - the value could be `nil`                                                                                                                                                                                                       |
@@ -303,6 +343,8 @@ We replace it with `**` for conciseness.
 | `**::TextArray`                 | `text_array`     | `default_value`<br>(`array[string]`)     | `min_length`(`integer`) - minimum value length allowed, for each element<br>`max_length`(`integer`) - maximum value length allowed, for each element<br>`min_size`(`integer`) - minimum value size<br>`max_size`(`integer`) - maximum value size                                                                |
 | _Your custom class can be here_ | _..._            | _..._                                    | _..._                                                                                                                                                                                                                                                                                                           |
 
+</details>
+
 **Note:** Options marked with **\*** are mandatory.
 
 ### Search Functionality
@@ -348,14 +390,18 @@ Key details:
 
 Supported _operations_ and _operators_ for each _Active Field_ type are listed below.
 
-#### Boolean
+<details>
+<summary><strong>Boolean</strong></summary>
 
 | Operation  | Operator | Description                 |
 |------------|----------|-----------------------------|
 | `eq`       | `=`      | Value is equal to given     |
 | `not_eq`   | `!=`     | Value is not equal to given |
 
-#### Date
+</details>
+
+<details>
+<summary><strong>Date</strong></summary>
 
 | Operation  | Operator | Description                             |
 |------------|----------|-----------------------------------------|
@@ -366,7 +412,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `lt`       | `<`      | Value is less than given                |
 | `lteq`     | `<=`     | Value is less than or equal to given    |
 
-#### DateArray
+</details>
+
+<details>
+<summary><strong>DateArray</strong></summary>
 
 | Operation     | Operator | Description                                                    |
 |---------------|----------|----------------------------------------------------------------|
@@ -387,7 +436,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `size_lt`     | `#<`     | Array value size is less than given                            |
 | `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
 
-#### DateTime
+</details>
+
+<details>
+<summary><strong>DateTime</strong></summary>
 
 | Operation  | Operator | Description                             |
 |------------|----------|-----------------------------------------|
@@ -398,7 +450,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `lt`       | `<`      | Value is less than given                |
 | `lteq`     | `<=`     | Value is greater than or equal to given |
 
-#### DateTimeArray
+</details>
+
+<details>
+<summary><strong>DateTimeArray</strong></summary>
 
 | Operation     | Operator | Description                                                    |
 |---------------|----------|----------------------------------------------------------------|
@@ -419,7 +474,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `size_lt`     | `#<`     | Array value size is less than given                            |
 | `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
 
-#### Decimal
+</details>
+
+<details>
+<summary><strong>Decimal</strong></summary>
 
 | Operation  | Operator | Description                             |
 |------------|----------|-----------------------------------------|
@@ -430,7 +488,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `lt`       | `<`      | Value is less than given                |
 | `lteq`     | `<=`     | Value is greater than or equal to given |
 
-#### DecimalArray
+</details>
+
+<details>
+<summary><strong>DecimalArray</strong></summary>
 
 | Operation     | Operator | Description                                                    |
 |---------------|----------|----------------------------------------------------------------|
@@ -451,14 +512,20 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `size_lt`     | `#<`     | Array value size is less than given                            |
 | `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
 
-#### Enum
+</details>
+
+<details>
+<summary><strong>Enum</strong></summary>
 
 | Operation  | Operator | Description                 |
 |------------|----------|-----------------------------|
 | `eq`       | `=`      | Value is equal to given     |
 | `not_eq`   | `!=`     | Value is not equal to given |
 
-#### EnumArray
+</details>
+
+<details>
+<summary><strong>EnumArray</strong></summary>
 
 | Operation     | Operator | Description                                        |
 |---------------|----------|----------------------------------------------------|
@@ -471,7 +538,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `size_lt`     | `#<`     | Array value size is less than given                |
 | `size_lteq`   | `#<=`    | Array value size is less than or equal to given    |
 
-#### Integer
+</details>
+
+<details>
+<summary><strong>Integer</strong></summary>
 
 | Operation  | Operator | Description                             |
 |------------|----------|-----------------------------------------|
@@ -482,7 +552,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `lt`       | `<`      | Value is less than given                |
 | `lteq`     | `<=`     | Value is greater than or equal to given |
 
-#### IntegerArray
+</details>
+
+<details>
+<summary><strong>IntegerArray</strong></summary>
 
 | Operation     | Operator | Description                                                    |
 |---------------|----------|----------------------------------------------------------------|
@@ -503,7 +576,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `size_lt`     | `#<`     | Array value size is less than given                            |
 | `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
 
-#### Text
+</details>
+
+<details>
+<summary><strong>Text</strong></summary>
 
 | Operation         | Operator | Description                                                 |
 |-------------------|----------|-------------------------------------------------------------|
@@ -522,7 +598,10 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `not_iend_with`   | `!$*`    | Value doesn't end with given substring (case-insensitive)   |
 | `not_icontain`    | `!~*`    | Value doesn't contain given substring (case-insensitive)    |
 
-#### TextArray
+</details>
+
+<details>
+<summary><strong>TextArray</strong></summary>
 
 | Operation        | Operator | Description                                                 |
 |------------------|----------|-------------------------------------------------------------|
@@ -537,6 +616,8 @@ Supported _operations_ and _operators_ for each _Active Field_ type are listed b
 | `size_lt`        | `#<`     | Array value size is less than given                         |
 | `size_lteq`      | `#<=`    | Array value size is less than or equal to given             |
 
+</details>
+
 ## Configuration
 
 ### Limiting Field Types for a Customizable
@@ -849,6 +930,97 @@ IpFinder.new(active_field: ip_active_field).search(op: "eq", value: "127.0.0.1")
 IpArrayFinder.new(active_field: ip_array_active_field).search(op: "#>=", value: 5)
 ```
 
+### Multi-tenancy (scoping)
+
+The scoping feature enables multi-tenancy or context-based field definitions per model.
+It allows you to define different sets of _Active Fields_ for different scopes (e.g., different tenants, organizations, or contexts).
+
+**How it works:**
+- Pass a `scope_method` parameter to `has_active_fields` to enable scoping for a _Customizable_ model. The method should return a value that identifies the scope (e.g., `tenant_id`, `organization_id`).
+- The scope method's return value is automatically converted to a string and exposed as `active_fields_scope` on each _Customizable_ record. This value is used to match against _Active Field_ `scope` values.
+- When an _Active Field_ has `scope` = `nil` (_global field_), it is available to all _Customizable_ records, regardless of their scope value.
+- When an _Active Field_ has a `scope` != `nil` (_scope field_), it is only available to _Customizable_ records where `active_fields_scope` matches the `scope`.
+
+```ruby
+class User < ApplicationRecord
+  has_active_fields scope_method: :tenant_id
+end
+
+# Global active field (available to all users)
+ActiveFields::Field::Text.create!(
+  name: "note",
+  customizable_type: "User",
+  scope: nil,
+)
+
+# Scoped active field (only available to users with tenant_id = "tenant_1")
+ActiveFields::Field::Integer.create!(
+  name: "age",
+  customizable_type: "User",
+  scope: "tenant_1",
+)
+
+# Scoped active field (only available to users with tenant_id = "tenant_2")
+ActiveFields::Field::Date.create!(
+  name: "registered_on",
+  customizable_type: "User",
+  scope: "tenant_2",
+)
+
+# Usage
+user_1 = User.create!(tenant_id: "tenant_1")
+user_1.active_fields # Returns `note` and `age`
+
+user_2 = User.create!(tenant_id: "tenant_2")
+user_2.active_fields # Returns `note` and `registered_on`
+
+user_3 = User.create!(tenant_id: nil)
+user_3.active_fields # Returns only `note`
+
+# Query with scope
+User.active_fields # Returns only `note`
+User.active_fields(scope: "tenant_1") # Returns `note` and `age`
+User.where_active_fields(filters) # Search by global fields only (`note`)
+User.where_active_fields(filters, scope: "tenant_1") # Search by `note` and `registered_on`
+```
+
+**Handling scope changes:**
+
+If you change the scope value of a _Customizable_ record (e.g., changing `tenant_id`), you must manually destroy _Active Values_ that are no longer available for that record.
+The gem does not automatically handle this because the `scope_method` implementation is up to you, and therefore its change tracking is your responsibility.
+However, there is a helper method that you could use to clear the _Active Values_ list: `clear_unavailable_active_values`.
+
+**Example 1:** `scope_method` is a single database column.
+
+```ruby
+class User < ApplicationRecord
+  has_active_fields scope_method: :tenant_id
+
+  after_update :clear_unavailable_active_values, if: :saved_change_to_tenant_id?
+end
+```
+
+**Example 2:** `scope_method` is a computed value from multiple columns.
+
+```ruby
+class User < ApplicationRecord
+  has_active_fields scope_method: :tenant_and_department_scope
+
+  # The scope method should return a string
+  def tenant_and_department_scope
+    "#{tenant_id}-#{department_id}"
+  end
+
+  after_update :clear_unavailable_active_values, if: :tenant_and_department_scope_changed?
+
+  private
+
+  def tenant_and_department_scope_changed?
+    saved_change_to_tenant_id? || saved_change_to_department_id?
+  end
+end
+```
+
 ### Localization (I18n)
 
 The built-in _validators_ primarily use _Rails_ default error types.
@@ -861,9 +1033,7 @@ For an example, refer to the [locale file](https://github.com/lassoid/active_fie
 
 ## Current Restrictions
 
-1. Only _PostgreSQL_ 17+ is fully supported.
-
-    The gem is tested exclusively with _PostgreSQL_. Support for other databases is not guaranteed.
+1. This gem requires _PostgreSQL_ and is not designed to support other database systems.
 
 2. Updating some _Active Fields_ options may be unsafe.
 
@@ -901,6 +1071,7 @@ active_field.available_customizable_types # Available Customizable types for thi
 
 # Scopes:
 ActiveFields::Field::Boolean.for("Post") # Collection of Active Fields registered for the specified Customizable type
+ActiveFields::Field::Integer.for("User", scope: "main_tenant") # Collection of Active Fields available for the specified Customizable type with given scope
 ```
 
 ### Values API
@@ -929,10 +1100,13 @@ customizable = Post.take
 customizable.active_values # `has_many` association with Active Values linked to this Customizable
 
 # Methods:
-customizable.active_fields # Collection of Active Fields registered for this record
-Post.active_fields # Collection of Active Fields registered for this model
+customizable.active_fields # Collection of Active Fields available for this record
+customizable.active_fields_scope # Scope value for this record
+Post.active_fields # Collection of Active Fields available for this model
+User.active_fields(scope: "main_tenant") # Collection of Active Fields available for this model and given scope
 Post.allowed_active_fields_type_names # Active Fields type names allowed for this Customizable model
 Post.allowed_active_fields_class_names # Active Fields class names allowed for this Customizable model
+User.active_fields_scope_method # Scope method for this model
 
 # Create, update or destroy Active Values.
 customizable.active_fields_attributes = [
@@ -963,6 +1137,10 @@ customizable.active_values_attributes = attributes
 # `form.fields_for :active_fields, customizable.initialize_active_values`.
 customizable.initialize_active_values
 
+# Destroys Active Values that are no longer associated with Active Fields available for this record.
+# Call this method after changing the scope value to ensure all Active Values are valid.
+customizable.clear_unavailable_active_values
+
 # Query Customizables by Active Values.
 Post.where_active_fields(
   [
@@ -971,6 +1149,11 @@ Post.where_active_fields(
     { n: "boolean", op: "!=", v: false }, # compact form (string or symbol keys)
   ],
 )
+# Search with given scope.
+User.where_active_fields(
+  filters,
+  scope: "main_tenant",
+)
 ```
 
 ### Global Config
@@ -1013,14 +1196,7 @@ and push the `.gem` file to [rubygems.org](https://rubygems.org).
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/lassoid/active_fields.
-This project is intended to be a safe, welcoming space for collaboration, and contributors
-are expected to adhere to the [code of conduct](https://github.com/lassoid/active_fields/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the ActiveFields project's codebases, issue trackers, chat rooms and mailing lists
-is expected to follow the [code of conduct](https://github.com/lassoid/active_fields/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -5,6 +5,4 @@ require "bundler/setup"
 APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
-load "rails/tasks/statistics.rake"
-
 require "bundler/gem_tasks"

data/app/models/concerns/active_fields/customizable_concern.rb

@@ -23,6 +23,10 @@ module ActiveFields
       # - <tt>:op</tt> or <tt>:operator</tt> key specifying search operation or operator;
       # - <tt>:v</tt> or <tt>:value</tt> key specifying search value.
       #
+      # Optionally, a <tt>:scope</tt> keyword argument can be provided to expand the search
+      # to include both global fields (where scope is nil) and scoped fields for the given scope.
+      # When <tt>:scope</tt> is omitted or nil, only global fields are searched.
+      #
       # Example:
       #
       #   # Array of hashes
@@ -45,7 +49,13 @@ module ActiveFields
       #
       #   # Params (must be permitted)
       #   CustomizableModel.where_active_fields(permitted_params)
-      scope :where_active_fields, ->(filters) do
+      #
+      #   # Scoped
+      #   CustomizableModel.where_active_fields(
+      #     filters,
+      #     scope: Current.tenant.id,
+      #   )
+      scope :where_active_fields, ->(filters, scope: nil) do
         filters = filters.to_h if filters.respond_to?(:permitted?)
 
         unless filters.is_a?(Array) || filters.is_a?(Hash)
@@ -55,23 +65,27 @@ module ActiveFields
         # Handle `fields_for` params
         filters = filters.values if filters.is_a?(Hash)
 
-        active_fields_by_name = active_fields.index_by(&:name)
+        active_fields_by_name = active_fields(scope: scope).index_by(&:name)
 
-        filters.inject(self) do |scope, filter|
+        filters.inject(self) do |query, filter|
           filter = filter.to_h if filter.respond_to?(:permitted?)
           filter = filter.with_indifferent_access
 
-          active_field = active_fields_by_name[filter[:n] || filter[:name]]
-          next scope if active_field.nil?
-          next scope if active_field.value_finder.nil?
+          name = filter.key?(:n) ? filter[:n] : filter[:name]
+          operator = filter.key?(:op) ? filter[:op] : filter[:operator]
+          value = filter.key?(:v) ? filter[:v] : filter[:value]
+
+          active_field = active_fields_by_name[name]
+          next query if active_field.nil?
+          next query if active_field.value_finder.nil?
 
           active_values = active_field.value_finder.search(
-            op: filter[:op] || filter[:operator],
-            value: filter[:v] || filter[:value],
+            op: operator,
+            value: value,
           )
-          next scope if active_values.nil?
+          next query if active_values.nil?
 
-          scope.where(id: active_values.select(:customizable_id))
+          query.where(id: active_values.select(:customizable_id))
         end
       end
 
@@ -79,9 +93,13 @@ module ActiveFields
     end
 
     class_methods do
-      # Collection of active fields registered for this customizable
-      def active_fields
-        ActiveFields.config.field_base_class.for(name)
+      # Returns the collection of active fields associated with this customizable model.
+      # You can provide an optional <tt>:scope</tt> parameter
+      # to retrieve active fields available for a specific scope, not just global fields.
+      def active_fields(scope: nil)
+        scope = nil if active_fields_scope_method.nil?
+
+        ActiveFields.config.field_base_class.for(name, scope: scope)
       end
 
       # Returns active fields type names allowed for this customizable model.
@@ -95,7 +113,17 @@ module ActiveFields
       end
     end
 
-    delegate :active_fields, to: :class
+    # Collection of active fields registered for this customizable.
+    def active_fields
+      self.class.active_fields(scope: active_fields_scope)
+    end
+
+    # Scope value for the active fields collection.
+    def active_fields_scope
+      return if self.class.active_fields_scope_method.nil?
+
+      send(self.class.active_fields_scope_method)&.to_s
+    end
 
     # Assigns the given attributes to the active_values association.
     #
@@ -177,5 +205,29 @@ module ActiveFields
 
       active_values
     end
+
+    # Destroys all active_values that are no longer available for this customizable
+    # (e.g. after its scope has changed).
+    #
+    # This method is suitable for customizables with scope functionality enabled
+    # (when `has_active_fields` is called with a `scope_method:` parameter).
+    # When a customizable's scope value changes,
+    # some active_values may reference active_fields that are no longer available for the new scope.
+    # This method identifies and destroys those orphaned active_values.
+    #
+    # Example:
+    #
+    #   class User < ApplicationRecord
+    #     has_active_fields scope_method: :tenant_id
+    #
+    #     after_update :clear_unavailable_active_values, if: :saved_change_to_tenant_id?
+    #   end
+    def clear_unavailable_active_values
+      available_field_ids = active_fields.pluck(:id)
+
+      active_values.select do |active_value|
+        available_field_ids.exclude?(active_value.active_field_id)
+      end.each(&:destroy)
+    end
   end
 end