active_fields 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d32fccb9d7af7eab0db169ea67d7046e09d6f8eace84e0a2c49f32574377543
-  data.tar.gz: 0fa74f41f48702355d9fc73f64d49389433f03e94b62e5d3e2552fcff01ec7f3
+  metadata.gz: 6eaf6bd2afd182c6429e472d3f2b1a3dd70bd7a7baadd9a2bbc7dc421a39a7d7
+  data.tar.gz: 6d77769c25f2c97bae25bee0ed66792fd719f4738610fa9b6f1c8d92f77f673a
 SHA512:
-  metadata.gz: 6e76f8e6e24e1b65a8d16480b06ce348c0d777dae4be55ec4fd908d82b17752d69866d9e73cee2847dafa1b04800977d34048eac8f0e7efc61644ddc2f30ae07
-  data.tar.gz: 673b3a37fcd8f2a1e0ee0d40bb3f80192d2a24933e097aae4d76d1a34d9fb04850a2b5504d2301b70cdbf2226a43bd96fd0bda0e58314aaf6ff3f54d2b7e0237
+  metadata.gz: 78359ebaf1b2048564eed04a8de2464aa4650d3e16a03c9f701041daaae96c7c30924fd685d15aed7180dfccf340e86509db1a0bf08dcebd1fd72ee763b1d9a9
+  data.tar.gz: 51680b929b2de155eb75e16efa328ff76e28dc0112f315ce350c378cc6fe4f77e7fee040c58a23626af7026b0afc008beac6e0a16be8892cdb89c192eaed0a5b

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,4 +1,14 @@
 ## [Unreleased]
+
+## [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
 - Drop support for _Rails_ < 7.1
 - Drop support for _Ruby_ < 3.1 (EOL)
 - Added search functionality

data/README.md

@@ -38,6 +38,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:
@@ -849,6 +855,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)
 ```
 
+### 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 +958,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 +996,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 +1025,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 +1062,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 +1074,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 +1121,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

@@ -6,14 +6,12 @@ module ActiveFields
     extend ActiveSupport::Concern
 
     included do
-      # rubocop:disable Rails/ReflectionClassName
       has_many :active_values,
         class_name: ActiveFields.config.value_class_name,
         as: :customizable,
         inverse_of: :customizable,
         autosave: true,
         dependent: :destroy
-      # rubocop:enable Rails/ReflectionClassName
 
       # Searches customizables by active_values.
       #
@@ -25,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
@@ -47,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)
@@ -57,23 +65,23 @@ 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?
+          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],
           )
-          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
 
@@ -81,9 +89,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.
@@ -97,7 +109,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.
     #
@@ -179,5 +201,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

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

@@ -6,23 +6,28 @@ module ActiveFields
     extend ActiveSupport::Concern
 
     included do
-      # rubocop:disable Rails/ReflectionClassName
       has_many :active_values,
         class_name: ActiveFields.config.value_class_name,
         foreign_key: :active_field_id,
         inverse_of: :active_field,
         dependent: :destroy
-      # rubocop:enable Rails/ReflectionClassName
 
-      scope :for, ->(customizable_type) { where(customizable_type: customizable_type) }
+      # Returns active fields for the given customizable type, including both
+      # scoped fields (when scope parameter is provided) and global fields (where scope is nil).
+      scope :for, ->(customizable_type, scope: nil) do
+        # Global fields are available to all records of the given customizable type.
+        scopes = [scope, nil].uniq
+        where(customizable_type: customizable_type, scope: scopes)
+      end
 
       validates :type, presence: true
-      validates :name, presence: true, uniqueness: { scope: :customizable_type }
-      validates :name, format: { with: /\A[a-z0-9_]+\z/ }, allow_blank: true
+      validates :name, presence: true
+      validate :validate_name_uniqueness
       validate :validate_default_value
       validate :validate_customizable_model_allows_type
 
       after_initialize :set_defaults
+      before_validation :set_scope
     end
 
     class_methods do
@@ -91,7 +96,7 @@ module ActiveFields
 
     # Returns customizable types that allow this field type.
     #
-    # Notes:
+    # NOTE:
     # - The customizable model must be loaded to appear in this list.
     #   Relationships between customizable models and field types are established in the `has_active_fields` method,
     #   which is typically called within the customizable model.
@@ -106,6 +111,26 @@ module ActiveFields
 
     private
 
+    # NOTE: The uniqueness constraint in the DB does not fully enforce this validation:
+    # Records where scope is NULL do not prevent the existence of records with the same
+    # [name, customizable_type] but with a non-NULL scope, and vice versa.
+    def validate_name_uniqueness
+      base_scope =
+        ActiveFields.config.field_base_class.excluding(self).where(customizable_type: customizable_type, name: name)
+
+      if scope.nil?
+        if base_scope.exists?
+          errors.add(:name, :taken)
+          return false
+        end
+      elsif base_scope.exists?(scope: [scope, nil])
+        errors.add(:name, :taken)
+        return false
+      end
+
+      true
+    end
+
     def validate_default_value
       validator = value_validator
       return if validator.validate(default_value)
@@ -130,5 +155,12 @@ module ActiveFields
     end
 
     def set_defaults; end
+
+    # Forces scope to nil if the customizable model does not have a scope method.
+    def set_scope
+      return if customizable_model.nil?
+
+      self.scope = nil if customizable_model.active_fields_scope_method.nil?
+    end
   end
 end

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

@@ -7,12 +7,10 @@ module ActiveFields
 
     included do
       belongs_to :customizable, polymorphic: true, optional: false, inverse_of: :active_values
-      # rubocop:disable Rails/ReflectionClassName
       belongs_to :active_field,
         class_name: ActiveFields.config.field_base_class_name,
         optional: false,
         inverse_of: :active_values
-      # rubocop:enable Rails/ReflectionClassName
 
       validates :active_field, uniqueness: { scope: :customizable }
       validate :validate_value
@@ -61,7 +59,14 @@ module ActiveFields
 
     def validate_customizable_allowed
       return true if active_field.nil?
-      return true if customizable_type == active_field.customizable_type
+
+      if customizable_type != active_field.customizable_type
+        errors.add(:customizable, :invalid)
+        return false
+      end
+
+      return true if active_field.scope.nil?
+      return true if customizable&.active_fields_scope == active_field.scope
 
       errors.add(:customizable, :invalid)
       false

data/db/migrate/20250229230000_add_scope_to_active_fields.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class AddScopeToActiveFields < ActiveRecord::Migration[7.1]
+  def change
+    change_table :active_fields do |t|
+      t.string :scope
+
+      t.remove_index %i[name customizable_type], unique: true
+      t.remove_index :customizable_type
+
+      t.index %i[customizable_type scope name], unique: true, nulls_not_distinct: true
+    end
+  end
+end

data/gemfiles/rails_7.1.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "puma"
+gem "propshaft"
+gem "importmap-rails"
+gem "stimulus-rails"
+gem "rails", "~> 7.1.0"
+
+group :development do
+  gem "web-console"
+end
+
+gemspec path: "../"

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "puma"
+gem "propshaft"
+gem "importmap-rails"
+gem "stimulus-rails"
+gem "rails", "~> 7.2.0"
+
+group :development do
+  gem "web-console"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "puma"
+gem "propshaft"
+gem "importmap-rails"
+gem "stimulus-rails"
+gem "rails", "~> 8.0.0"
+
+group :development do
+  gem "web-console"
+end
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,15 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "puma"
+gem "propshaft"
+gem "importmap-rails"
+gem "stimulus-rails"
+gem "rails", "~> 8.1.0"
+
+group :development do
+  gem "web-console"
+end
+
+gemspec path: "../"

data/lib/active_fields/casters/date_array_caster.rb

@@ -6,13 +6,13 @@ module ActiveFields
       def serialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
 
       def deserialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
     end
   end

data/lib/active_fields/casters/date_time_array_caster.rb

@@ -6,13 +6,13 @@ module ActiveFields
       def serialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
 
       def deserialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
     end
   end

data/lib/active_fields/casters/decimal_array_caster.rb

@@ -6,13 +6,13 @@ module ActiveFields
       def serialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
 
       def deserialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
     end
   end

data/lib/active_fields/casters/enum_array_caster.rb

@@ -6,13 +6,13 @@ module ActiveFields
       def serialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
 
       def deserialize(value)
         return unless value.is_a?(Array)
 
-        value.map { super(_1) }
+        value.map { |element| super(element) }
       end
     end
   end