voids 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b79995cb20862d8567f3031c8bf0a8a12dd9501ce8be84dbdf31472f3e2aac
-  data.tar.gz: 3150180efa5c939ab91e70fef7dc9c5b489d9155c504908629a1821ae454ccfc
+  metadata.gz: 2ddc0ec3f6eb944d0b91f7d661887b9ef36c7b6e02aa63606cf8eafff8a6c71a
+  data.tar.gz: 8fe0046ebed0bf511b7ce893a8e2cc48269233f7c617469c6e80e262d953d249
 SHA512:
-  metadata.gz: 7773cc74efa588e6d919e225e4338b2c79005f5153932f63b2cc2965857ce73ffebef0ed33dae093c1bfb3a9c92291e95459f4802a37a56c3049212025706356
-  data.tar.gz: 2c7d591765982c89822c1c968c6e15d6a9a7b10f2dda51035a42b014f0bb77fdf79056c4a0f96ac7c69774a0ff5961a070d183a044c9d37c5d39c169a0710c00
+  metadata.gz: 522dd880a0decbaadc5f8584e84ba822cf00f777653c829f618a7626a851a0088125c45c4ec25f382e56b7bf588a114f1a7edf5978794586bebfcb8e5a076a9c
+  data.tar.gz: 8135b1214dc06dae3f6e2e691a250a30a4708de8b661cc1b82ad96f05020ce5b10cfc1c6586e6044dd12fa0fdb94c823ef6851df4ee20acec95e7f9916fa11be

data/.circleci/config.yml

@@ -4,7 +4,7 @@ orbs:
 workflows:
   build:
     jobs:
-      - ruby-rails/lint:
+      - ruby-rails/lint-gem:
           name: lint
       - ruby-rails/test-gem:
           name: test

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config --auto-gen-only-exclude`
-# on 2026-09-14 20:55:19 UTC using RuboCop version 1.91.0.
+# on 2026-09-14 23:45:19 UTC using RuboCop version 1.91.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -19,10 +19,11 @@ Lint/SelfAssignment:
   Exclude:
     - 'spec/voids/normalization_spec.rb'
 
-# Offense count: 7
+# Offense count: 8
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
+    - 'lib/voids/associations.rb'
     - 'lib/voids/base.rb'
     - 'lib/voids/nested_attributes.rb'
 

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+- Add `changes_applied:` option to `Voids::Base#assign_attributes` so callers can bulk-assign attributes without resetting dirty tracking.
+- Propagate validation context to nested forms during parent validation.
+- Validate nested forms even when parent validations fail, so nested errors still bubble up.
+- Add `Voids::Base#empty?` with default emptiness semantics based on blank attributes.
+- Make `AssociationProxy#any?` block-aware (matching Ruby collection semantics).
+- Add `AssociationProxy#reverse` for array-like read access without explicit `to_a` conversion.
+
 ## [1.0.0] - 2026-01-13
 
 - Initial release

data/README.md

@@ -1,3 +1,7 @@
+[![Gem version](https://badge.fury.io/rb/voids.svg)](https://badge.fury.io/rb/voids)
+[![CircleCI](https://dl.circleci.com/status-badge/img/gh/sul-dlss/voids/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/sul-dlss/voids/tree/main)
+[![Codecov](https://codecov.io/github/sul-dlss/voids/graph/badge.svg?token=5PZ9TARO34)](https://codecov.io/github/sul-dlss/voids)
+
 # Voids
 
 _fill it in_.
@@ -36,6 +40,9 @@ form = PostForm.new(title: "hello", content: "world")
 form.valid? # true
 ```
 
+`Voids::Base` includes a default `empty?` implementation: a form is empty when all `attributes` values are blank.
+Override this in subclasses if your form uses custom emptiness semantics.
+
 ### Inheriting attributes from models
 
 Pull attribute definitions from existing models instead of manually defining each one.
@@ -129,6 +136,20 @@ form.images.new(url: "https://example.com/image.jpg")
 form.images.count # 1
 ```
 
+`has_many` associations return a collection proxy that supports common collection methods:
+
+```ruby
+form.images.any? # true/false
+form.images.any? { |image| image.url.present? } # true/false
+form.images.reverse # array in reverse order
+```
+
+Notes:
+
+1. `any?` supports both no-block and block forms.
+2. `reverse` returns a reversed array view and does not mutate the underlying proxy order.
+3. `to_a` is still available when explicit array conversion is desired.
+
 ### Nested attributes from params
 
 ```ruby
@@ -168,13 +189,14 @@ form.from_model(post)
 
 ### Validation with nested forms
 
-Validations automatically cascade to nested forms:
+Validations automatically cascade to nested forms and use the same validation context:
 
 ```ruby
 form = PostForm.new(title: "hello")
 form.images.new(url: nil) # invalid image
 
 form.valid? # false
+form.valid?(:publish) # false
 form.errors.full_messages # includes nested form errors
 ```
 
@@ -285,6 +307,24 @@ form.title_was # "original"
 form.changes # { "title" => ["original", "changed"] }
 ```
 
+`assign_attributes` resets dirty tracking when it finishes, so the form reports
+itself as clean and the assignments move to `previous_changes`. Pass
+`changes_applied: false` to keep dirty tracking intact, which is useful when the
+caller needs to know what a params hash actually changed:
+
+```ruby
+form = PostForm.new(title: "original")
+form.assign_attributes(params[:post], changes_applied: false)
+
+form.changed? # true
+form.changes  # { "title" => ["original", "submitted"] }
+```
+
+Attributes can be passed positionally or as keywords; `:changes_applied` is
+never treated as an attribute. Nested forms assigned through `*_attributes=`
+writers still reset their own dirty tracking, since those writers follow the
+Rails setter convention and take no options.
+
 ### Normalization
 
 Normalize attribute values on assignment. Works on Rails 6+, not just 7.1+.

data/lib/voids/association_proxy.rb

@@ -55,8 +55,14 @@ module Voids
       @records.empty?
     end
 
-    def any?
-      @records.any?
+    def any?(&block)
+      return @records.any? unless block
+
+      @records.any?(&block)
+    end
+
+    def reverse
+      @records.reverse
     end
 
     def [](index)
@@ -68,6 +74,12 @@ module Voids
       @records_by_id.clear
     end
 
+    def replace(records)
+      clear
+      Array(records).each { |record| push(record) }
+      self
+    end
+
     def to_a
       @records
     end
@@ -80,8 +92,8 @@ module Voids
       false
     end
 
-    def valid?
-      @records.all?(&:valid?)
+    def valid?(context = nil)
+      @records.all? { it.valid?(context) }
     end
 
     def errors

data/lib/voids/associations.rb

@@ -49,7 +49,7 @@ module Voids
         end
 
         define_method("#{name}=") do |value|
-          instance_variable_set("@#{name}", value)
+          public_send(name).replace(value)
         end
 
         accepts_nested_attributes_for(name, primary_key: primary_key, **)

data/lib/voids/base.rb

@@ -87,7 +87,20 @@ module Voids
       assign_attributes(attributes) if attributes.present?
     end
 
-    def assign_attributes(new_attributes)
+    # Assigns the given attributes. Afterwards the form is marked as clean
+    # (dirty tracking is reset) unless `changes_applied: false` is given.
+    #
+    # Attributes may be passed positionally (`assign_attributes(params)`) or as
+    # keywords (`assign_attributes(title: 'new')`), so `:changes_applied` is
+    # extracted from the keywords rather than declared as a keyword argument.
+    def assign_attributes(new_attributes = nil, **options)
+      changes_applied = options.fetch(:changes_applied, true)
+      keyword_attributes = options.except(:changes_applied)
+      if new_attributes && keyword_attributes.any?
+        raise ArgumentError, 'pass attributes either positionally or as keywords, not both'
+      end
+
+      new_attributes ||= keyword_attributes
       return if new_attributes.blank?
 
       attrs = if new_attributes.respond_to?(:to_unsafe_h)
@@ -109,7 +122,7 @@ module Voids
         end
       end
 
-      changes_applied
+      self.changes_applied if changes_applied
     end
 
     def from_model(model)
@@ -176,7 +189,9 @@ module Voids
 
     def valid?(context = nil)
       run_callbacks :validation do
-        super(context) && nested_forms_valid?
+        parent_valid = super(context)
+        nested_valid = nested_forms_valid?(context)
+        parent_valid && nested_valid
       end
     end
 
@@ -215,32 +230,38 @@ module Voids
       attributes.except(*excluded_keys)
     end
 
+    def empty?
+      attributes.all? { |_name, value| value.blank? }
+    end
+
     private
 
-    def nested_forms_valid?
-      self.class.associations.all? do |name, association|
+    def nested_forms_valid?(context)
+      all_valid = true
+
+      self.class.associations.each do |name, association|
         nested_form = public_send(name)
-        next true if nested_form.nil?
+        next if nested_form.nil?
 
         case association[:type]
         when :has_one
-          if nested_form.valid?
-            true
-          else
-            copy_nested_errors(name, nested_form)
-            false
-          end
+          next if nested_form.valid?(context)
+
+          errors.add(name.to_sym, :invalid)
+          copy_nested_errors(name, nested_form)
+          all_valid = false
         when :has_many
-          if nested_form.valid?
-            true
-          else
-            nested_form.each_with_index do |form, index|
-              copy_nested_errors("#{name}[#{index}]", form) unless form.valid?
-            end
-            false
+          next if nested_form.valid?(context)
+
+          errors.add(name.to_sym, :invalid)
+          nested_form.each_with_index do |form, index|
+            copy_nested_errors("#{name}[#{index}]", form) unless form.valid?(context)
           end
+          all_valid = false
         end
       end
+
+      all_valid
     end
 
     def copy_nested_errors(association_name, nested_form)

data/lib/voids/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Voids
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 end

data/spec/voids/association_proxy_spec.rb

@@ -148,6 +148,14 @@ RSpec.describe Voids::AssociationProxy do
 
       expect(proxy.any?).to be(true)
     end
+
+    it 'supports block form' do
+      proxy = described_class.new('ItemForm')
+      proxy.new(url: 'first')
+      proxy.new(url: nil)
+
+      expect(proxy.any? { |item| item.url.nil? }).to be(true)
+    end
   end
 
   describe '#[]' do
@@ -172,6 +180,29 @@ RSpec.describe Voids::AssociationProxy do
     end
   end
 
+  describe '#replace' do
+    it 'replaces records and returns self' do
+      proxy = described_class.new('ItemForm')
+      original = proxy.new(url: 'first')
+      replacement = ItemForm.new(url: 'second')
+
+      result = proxy.replace([replacement])
+
+      expect(result).to eq(proxy)
+      expect(proxy.to_a).to eq([replacement])
+      expect(proxy.to_a).not_to include(original)
+    end
+
+    it 'clears records when passed nil' do
+      proxy = described_class.new('ItemForm')
+      proxy.new(url: 'first')
+
+      proxy.replace(nil)
+
+      expect(proxy).to be_empty
+    end
+  end
+
   describe '#to_a' do
     it 'returns the underlying array' do
       proxy = described_class.new('ItemForm')
@@ -182,32 +213,51 @@ RSpec.describe Voids::AssociationProxy do
     end
   end
 
+  describe '#reverse' do
+    it 'returns records in reverse order' do
+      proxy = described_class.new('ItemForm')
+      first = proxy.new(url: 'first')
+      second = proxy.new(url: 'second')
+
+      expect(proxy.reverse).to eq([second, first])
+      # Keep default forward iteration behavior unchanged.
+      expect(proxy.to_a).to eq([first, second])
+    end
+  end
+
   describe '#valid?' do
-    it 'returns true when all items are valid' do
-      valid_form_class = Class.new(Voids::Base) do
+    subject(:proxy) { described_class.new('ValidForm') }
+
+    let(:valid_form_class) do
+      Class.new(Voids::Base) do
         attribute :url, :string
         validates :url, presence: true
+        validates :url, format: { with: /\Ahttps:.+/, message: 'must be HTTPS' }, on: :final_setup
       end
+    end
+
+    before do
       stub_const('ValidForm', valid_form_class)
 
-      proxy = described_class.new('ValidForm')
       proxy.new(url: 'https://example.com')
+    end
 
-      expect(proxy.valid?).to be(true)
+    context 'when all items are valid' do
+      it { is_expected.to be_valid }
     end
 
-    it 'returns false when any item is invalid' do
-      valid_form_class = Class.new(Voids::Base) do
-        attribute :url, :string
-        validates :url, presence: true
+    context 'when validation context is set' do
+      before { proxy.new(url: 'http://example.com') }
+
+      it 'returns false' do
+        expect(proxy.valid?(:final_setup)).to be false
       end
-      stub_const('ValidForm', valid_form_class)
+    end
 
-      proxy = described_class.new('ValidForm')
-      proxy.new(url: 'https://example.com')
-      proxy.new(url: nil)
+    context 'when any item is invalid' do
+      before { proxy.new(url: nil) }
 
-      expect(proxy.valid?).to be(false)
+      it { is_expected.not_to be_valid }
     end
   end
 end

data/spec/voids/associations_spec.rb

@@ -181,5 +181,27 @@ RSpec.describe Voids::Associations do
 
       expect(item).to be_a(CustomForm)
     end
+
+    it 'replaces records in existing association proxy when assigned an array' do
+      nested_class = Class.new(Voids::Base) do
+        attribute :url, :string
+      end
+      stub_const('ImageForm', nested_class)
+
+      form_class = Class.new(Voids::Base) do
+        has_many :images
+      end
+
+      original = ImageForm.new(url: 'https://example.com/old')
+      replacement = ImageForm.new(url: 'https://example.com/new')
+      form = form_class.new
+      proxy = form.images
+      proxy << original
+
+      form.images = [replacement]
+
+      expect(form.images).to be(proxy)
+      expect(form.images.to_a).to eq([replacement])
+    end
   end
 end

data/spec/voids/base_spec.rb

@@ -85,6 +85,29 @@ RSpec.describe Voids::Base do
 
       expect(form.photo.url).to eq('https://example.com')
     end
+
+    it 'assigns keyword attributes alongside changes_applied' do
+      form_class = Class.new(described_class) do
+        attribute :title, :string
+      end
+
+      form = form_class.new
+      form.assign_attributes(title: 'new title', changes_applied: false)
+
+      expect(form.title).to eq('new title')
+    end
+
+    it 'raises when attributes are passed both positionally and as keywords' do
+      form_class = Class.new(described_class) do
+        attribute :title, :string
+        attribute :content, :string
+      end
+
+      form = form_class.new
+
+      expect { form.assign_attributes({ title: 'new title' }, content: 'new content') }
+        .to raise_error(ArgumentError, 'pass attributes either positionally or as keywords, not both')
+    end
   end
 
   describe '.from_model' do
@@ -280,6 +303,30 @@ RSpec.describe Voids::Base do
     end
   end
 
+  describe '#empty?' do
+    it 'returns true when all attributes are blank' do
+      form_class = Class.new(described_class) do
+        attribute :title, :string
+        attribute :count, :integer
+      end
+
+      form = form_class.new
+
+      expect(form.empty?).to be(true)
+    end
+
+    it 'returns false when any attribute is present' do
+      form_class = Class.new(described_class) do
+        attribute :title, :string
+        attribute :count, :integer
+      end
+
+      form = form_class.new(title: 'present')
+
+      expect(form.empty?).to be(false)
+    end
+  end
+
   describe '#valid?' do
     it 'returns true when all validations pass' do
       form_class = Class.new(described_class) do
@@ -314,6 +361,7 @@ RSpec.describe Voids::Base do
         has_one :photo
         attribute :title, :string
       end
+      stub_const('PhotoWrapperForm', form_class)
 
       form = form_class.new(title: 'test')
       form.build_photo
@@ -332,11 +380,14 @@ RSpec.describe Voids::Base do
         has_many :images
         attribute :title, :string
       end
+      stub_const('ImageGalleryForm', form_class)
 
       form = form_class.new(title: 'test')
       form.images.new
 
       expect(form.valid?).to be(false)
+      expect(form.errors.details[:images]).to include(error: :invalid)
+      expect(form.errors.messages.keys).to include(:'images[0].url')
     end
 
     it 'includes nested form errors in parent errors' do
@@ -350,12 +401,59 @@ RSpec.describe Voids::Base do
         has_one :photo
         attribute :title, :string
       end
+      stub_const('PhotoWrapperForm', form_class)
 
       form = form_class.new(title: 'test')
       form.build_photo
       form.valid?
 
-      expect(form.errors.messages.keys).to include(:'photo.url')
+      expect(form.errors.messages.keys).to include(:photo, :'photo.url')
+      expect(form.errors.details[:photo]).to include(error: :invalid)
+    end
+
+    it 'includes nested form errors in parent even when parent has errors' do
+      nested_class = Class.new(described_class) do
+        attribute :url, :string
+        validates :url, presence: true
+      end
+      stub_const('PhotoForm', nested_class)
+
+      form_class = Class.new(described_class) do
+        has_one :photo
+        attribute :title, :string
+        validates :title, presence: true
+      end
+      stub_const('ImageForm', form_class)
+
+      form = form_class.new
+      form.build_photo
+      form.valid?
+
+      expect(form.errors.messages.keys).to contain_exactly(:title, :photo, :'photo.url')
+      expect(form.errors.details[:photo]).to include(error: :invalid)
+    end
+
+    it 'passes the validation context to nested forms' do
+      nested_class = Class.new(described_class) do
+        attribute :url, :string
+        validates :url, presence: true
+        validates :url, format: { with: /\Ahttps:.+/, message: 'must be HTTPS' }, on: :final_setup
+      end
+      stub_const('PhotoForm', nested_class)
+
+      form_class = Class.new(described_class) do
+        has_one :photo
+        attribute :title, :string
+        validates :title, presence: true
+      end
+      stub_const('ImageForm', form_class)
+
+      form = form_class.new(title: 'Summer in Sicily')
+      form.build_photo(url: 'http://myspace.com/sicily-photos')
+      form.valid?(:final_setup)
+
+      expect(form.errors.messages.keys).to contain_exactly(:photo, :'photo.url')
+      expect(form.errors.details[:photo]).to include(error: :invalid)
     end
   end
 end

data/spec/voids/dirty_tracking_spec.rb

@@ -49,6 +49,42 @@ RSpec.describe 'Dirty tracking' do
     expect(form.changed?).to be(false)
   end
 
+  it 'clears changes after assign_attributes when changes_applied is true' do
+    form_class = Class.new(Voids::Base) do
+      attribute :title, :string
+    end
+
+    form = form_class.new(title: 'original')
+    form.title = 'changed'
+    form.assign_attributes({ title: 'new' }, changes_applied: true)
+
+    expect(form.changed?).to be(false)
+  end
+
+  it 'preserves earlier changes when changes_applied is false' do
+    form_class = Class.new(Voids::Base) do
+      attribute :title, :string
+      attribute :content, :string
+    end
+
+    form = form_class.new(title: 'original', content: 'original content')
+    form.title = 'changed'
+    form.assign_attributes({ content: 'new content' }, changes_applied: false)
+
+    expect(form.title_was).to eq('original')
+  end
+
+  it 'records the assignment as a change when changes_applied is false' do
+    form_class = Class.new(Voids::Base) do
+      attribute :title, :string
+    end
+
+    form = form_class.new(title: 'original')
+    form.assign_attributes({ title: 'new' }, changes_applied: false)
+
+    expect(form.changes).to eq('title' => %w[original new])
+  end
+
   it 'detects if any attributes changed' do
     form_class = Class.new(Voids::Base) do
       attribute :title, :string

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: voids
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Josh Brody