voids 2.0.0

data/README.md

@@ -0,0 +1,427 @@
+# Voids
+
+_fill it in_.
+
+Voids is a form object pattern that works with Rails form helpers and validations without requiring database persistence.
+
+Most forms don't map to a single database table; some don't map to the database at all. This gem provides form objects that implement the ActiveModel interface—associations, validations, nested attributes, dirty tracking—without requiring ActiveRecord.
+
+Built on ActiveModel, so the Rails conventions you already know work here. Use the same validations, callbacks, attribute types, and form helpers. Forms integrate with `form_with` and `fields_for` without configuration. Error handling, i18n, dirty tracking, and model naming all follow standard Rails patterns.
+
+## Installation
+
+You've done this before:
+
+```ruby
+gem 'voids'
+```
+
+
+## Usage
+
+### Basic form with attributes
+
+```ruby
+class PostForm < Voids::Base
+  attribute :title, :string
+  attribute :content, :string
+  attribute :created_at, :datetime, default: -> { Time.current }
+
+  validates :title, presence: true
+  validates :content, presence: true
+  validates :created_at, presence: true
+end
+
+form = PostForm.new(title: "hello", content: "world")
+form.valid? # true
+```
+
+### Inheriting attributes from models
+
+Pull attribute definitions from existing models instead of manually defining each one.
+
+```bash
+rails g model Post title:string content:text
+```
+
+```ruby
+class Post < ApplicationRecord; end
+
+class PostForm < Voids::Base
+  inherit_attributes_from Post, except: [:created_at, :updated_at]
+end
+```
+
+Use `only:` to include specific attributes:
+
+```ruby
+class PostForm < Voids::Base
+  inherit_attributes_from Post, only: [:title, :content]
+end
+```
+
+Inherited attributes work with `from_model` and preserve the model's attribute types.
+
+### Inheriting validations from models
+
+Copy validation rules from existing models.
+
+```ruby
+class Post < ApplicationRecord
+  validates :title, presence: true, length: { minimum: 3 }
+  validates :content, presence: true
+end
+
+class PostForm < Voids::Base
+  inherit_attributes_from Post, only: [:title, :content]
+  inherit_validations_from Post, only: [:title]
+
+  validates :content, presence: true, length: { minimum: 50 }
+end
+```
+
+Use `only:` and `except:` to control which validations are inherited.
+
+#### What doesn't copy
+
+Some validators are skipped because they don't translate cleanly to form objects:
+
+**Proc/lambda conditionals** - Validators with `if: -> { ... }` or `unless: -> { ... }` are skipped. The closure captures the source class context and won't work correctly on the form.
+
+```ruby
+validates :content, presence: true, if: -> { published? }
+```
+
+**Symbol conditionals** work fine, but the form must define the method:
+
+```ruby
+validates :content, presence: true, if: :published?
+
+def published?
+  status == "published"
+end
+```
+
+**Association validators** - `validates_associated` references ActiveRecord associations that don't exist on forms. These are always skipped.
+
+**Custom validators** work if they're `EachValidator` subclasses. Validators that call methods specific to the source model will fail at runtime.
+
+**Missing attributes** - If you inherit a validation for an attribute that doesn't exist on the form, it will raise at runtime. Use `inherit_attributes_from` first or define the attribute manually.
+
+### Associations
+
+```ruby
+class ImageForm < Voids::Base
+  attribute :url, :string
+  validates :url, presence: true
+end
+
+class PostForm < Voids::Base
+  has_one :cover_photo  # defaults to CoverPhotoForm
+  has_many :images      # defaults to ImageForm
+
+  attribute :title, :string
+  validates :title, presence: true
+end
+
+form = PostForm.new
+form.images.new(url: "https://example.com/image.jpg")
+form.images.count # 1
+```
+
+### Nested attributes from params
+
+```ruby
+params = {
+  title: "hello",
+  cover_photo_attributes: { url: "https://example.com/cover.jpg" },
+  images_attributes: [
+    { url: "https://example.com/1.jpg" },
+    { url: "https://example.com/2.jpg" }
+  ]
+}
+
+form = PostForm.new(params)
+form.cover_photo.url # "https://example.com/cover.jpg"
+form.images.count # 2
+```
+
+### Load from model
+
+Class method creates a new instance:
+
+```ruby
+post = Post.find(1)
+form = PostForm.from_model(post)
+
+form.title # value from post
+form.cover_photo.url # value from post.cover_photo
+form.images.count # post.images.count
+```
+
+Instance method for existing forms:
+
+```ruby
+form = PostForm.new
+form.from_model(post)
+```
+
+### Validation with nested forms
+
+Validations automatically cascade to nested forms:
+
+```ruby
+form = PostForm.new(title: "hello")
+form.images.new(url: nil) # invalid image
+
+form.valid? # false
+form.errors.full_messages # includes nested form errors
+```
+
+### Extracting attributes for persistence
+
+Use `model_attributes` for the form's own attributes:
+
+```ruby
+form = PostForm.new(title: "test")
+form.model_attributes # => { "title" => "test", "content" => nil }
+
+Post.create!(form.model_attributes)
+```
+
+Use `attributes` for all attributes including nested:
+
+```ruby
+form = PostForm.new(
+  title: "test",
+  images_attributes: [{ url: "image.jpg" }]
+)
+
+form.attributes
+# => {
+#   "title" => "test",
+#   "content" => nil,
+#   "images_attributes" => [{ "url" => "image.jpg" }]
+# }
+
+Post.create!(form.attributes) # works with accepts_nested_attributes_for
+```
+
+### ID tracking in nested forms
+
+When editing existing records, nested forms update by id:
+
+```ruby
+post = Post.find(1) # has images with id: 1, 2, 3
+form = PostForm.from_model(post)
+
+form.images_attributes = [
+  { id: 1, url: "updated.jpg" },  # updates existing
+  { url: "new.jpg" }               # creates new
+]
+
+form.images.count # 4 (3 original + 1 new)
+form.images[0].url # "updated.jpg"
+```
+
+Use `primary_key` option for non-id identifiers:
+
+```ruby
+class ImageForm < Voids::Base
+  attribute :uuid, :string
+  attribute :url, :string
+end
+
+class PostForm < Voids::Base
+  has_many :images, primary_key: :uuid
+end
+
+form = PostForm.new
+form.images.new(uuid: "abc-123", url: "original.jpg")
+
+form.images_attributes = [
+  { uuid: "abc-123", url: "updated.jpg" }  # updates by uuid
+]
+
+form.images.first.url # "updated.jpg"
+```
+
+Works with `has_one` and `has_many`. Defaults to `:id`.
+
+### Destroying nested forms
+
+Mark nested records for deletion with `allow_destroy: true`:
+
+```ruby
+class PostForm < Voids::Base
+  has_many :images, allow_destroy: true
+end
+
+post = Post.find(1) # has images with id: 1, 2, 3
+form = PostForm.from_model(post)
+
+form.images_attributes = [
+  { id: 1, url: "updated.jpg" },  # updates existing
+  { id: 2, _destroy: true },      # marks for deletion
+  { url: "new.jpg" }               # creates new
+]
+
+form.images[1].marked_for_destruction? # true
+form.attributes["images_attributes"][1]["_destroy"] # true
+```
+
+When extracting attributes, records marked for destruction include `_destroy: true`. Works with has_one and has_many.
+
+### Dirty tracking
+
+Track attribute changes:
+
+```ruby
+form = PostForm.new(title: "original")
+form.title = "changed"
+
+form.title_changed? # true
+form.title_was # "original"
+form.changes # { "title" => ["original", "changed"] }
+```
+
+### Normalization
+
+Normalize attribute values on assignment. Works on Rails 6+, not just 7.1+.
+
+Normalization is idempotent—applying it multiple times produces the same result as applying it once.
+
+```ruby
+class UserForm < Voids::Base
+  attribute :email, :string
+  attribute :phone, :string
+
+  normalizes :email, with: ->(email) { email.strip.downcase }
+  normalizes :phone, with: ->(phone) { phone.delete("^0-9").delete_prefix("1") }
+end
+
+form = UserForm.new(email: " TEST@EXAMPLE.COM\n")
+form.email # "test@example.com"
+
+form = UserForm.new(phone: "1-555-123-4567")
+form.phone # "5551234567"
+```
+
+Normalize multiple attributes with one call:
+
+```ruby
+class PostForm < Voids::Base
+  attribute :title, :string
+  attribute :author, :string
+
+  normalizes :title, :author, with: ->(value) { value.strip }
+end
+```
+
+By default, normalization skips nil values. Override with `apply_to_nil: true`:
+
+```ruby
+normalizes :email, with: ->(email) { email || "default@example.com" }, apply_to_nil: true
+```
+
+### Callbacks
+
+Hook into the validation lifecycle:
+
+```ruby
+class PostForm < Voids::Base
+  attribute :title, :string
+
+  before_validation :normalize_title
+  after_validation :log_errors
+
+  def normalize_title
+    self.title = title&.strip&.downcase
+  end
+
+  def log_errors
+    Rails.logger.error(errors.full_messages) if errors.any?
+  end
+end
+```
+
+### Rails form integration
+
+#### model naming
+
+Form classes automatically strip the "Form" suffix for Rails form helpers:
+
+```ruby
+class PostForm < Voids::Base
+  attribute :title, :string
+end
+
+form = PostForm.new
+form.model_name.param_key # "post"
+# rails generates: <input name="post[title]">
+```
+
+Override when needed:
+
+```ruby
+class AdminArticleForm < Voids::Base
+  model_name_for :article
+end
+
+form.model_name.param_key # "article"
+```
+
+#### persistence detection
+
+Forms automatically detect persistence via the `id` attribute:
+
+```ruby
+class PostForm < Voids::Base
+  attribute :id, :integer
+  attribute :title, :string
+end
+
+form = PostForm.new
+form.persisted? # false
+
+form = PostForm.new(id: 123)
+form.persisted? # true
+form.to_param # "123"
+```
+
+Override for custom logic:
+
+```ruby
+class PostForm < Voids::Base
+  def persisted?
+    # custom logic
+  end
+
+  def to_param
+    # custom logic
+  end
+end
+```
+
+#### i18n
+
+Standard ActiveModel translation support:
+
+```yaml
+# config/locales/en.yml
+en:
+  activemodel:
+    attributes:
+      post:  # uses model_name, not PostForm
+        title: "Post Title"
+    errors:
+      models:
+        post:
+          attributes:
+            title:
+              blank: "must be provided"
+```
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/advanced_features_example.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'voids'
+
+class ImageForm < Voids::Base
+  attribute :id, :integer
+  attribute :url, :string
+  attribute :caption, :string
+
+  validates :url, presence: true
+end
+
+class PostForm < Voids::Base
+  has_many :images
+
+  attribute :id, :integer
+  attribute :title, :string
+  attribute :content, :string
+
+  validates :title, presence: true
+
+  before_validation :normalize_title
+
+  def normalize_title
+    self.title = title&.strip if title
+  end
+end
+
+puts '=== dirty tracking ==='
+form = PostForm.new(title: 'original')
+puts "initial: #{form.title}"
+
+form.title = 'changed'
+puts "changed?: #{form.title_changed?}"
+puts "was: #{form.title_was}"
+puts "changes: #{form.changes.inspect}"
+
+puts "\n=== callbacks ==="
+form = PostForm.new(title: '  HELLO  ')
+form.valid?
+puts "normalized title: #{form.title}"
+
+puts "\n=== model_attributes (just top-level) ==="
+form = PostForm.new(title: 'test', content: 'content')
+form.images.new(url: 'image.jpg')
+puts form.model_attributes.inspect
+
+puts "\n=== attributes (includes nested) ==="
+puts form.attributes.inspect
+
+puts "\n=== id tracking in nested forms ==="
+mock_image1 = Struct.new(:id, :url, :caption).new(1, 'original1.jpg', 'first')
+mock_image2 = Struct.new(:id, :url, :caption).new(2, 'original2.jpg', 'second')
+mock_post = Struct.new(:id, :title, :content, :images).new(
+  100,
+  'my post',
+  'my content',
+  [mock_image1, mock_image2]
+)
+
+form = PostForm.from_model(mock_post)
+puts "loaded from model, images count: #{form.images.count}"
+
+form.images_attributes = [
+  { id: 1, url: 'updated1.jpg' },
+  { url: 'new.jpg', caption: 'new image' }
+]
+
+puts "after update, images count: #{form.images.count}"
+puts "image 1 url: #{form.images[0].url}"
+puts "image 2 url: #{form.images[1].url}"
+puts "image 3 url: #{form.images[2].url}"
+
+puts "\n=== using with activerecord ==="
+puts 'for create:'
+puts 'Post.create!(form.attributes)'
+puts form.attributes.inspect
+
+puts "\nfor update:"
+puts 'post.update!(form.model_attributes)'
+puts form.model_attributes.inspect

data/examples/assign_from_model_example.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'voids'
+
+class ImageForm < Voids::Base
+  attribute :url, :string
+  attribute :caption, :string
+
+  validates :url, presence: true
+end
+
+class CoverPhotoForm < Voids::Base
+  attribute :url, :string
+
+  validates :url, presence: true
+end
+
+class PostForm < Voids::Base
+  has_one :cover_photo
+  has_many :images
+
+  attribute :title, :string
+  attribute :content, :string
+  attribute :created_at, :datetime
+
+  validates :title, presence: true
+  validates :content, presence: true
+  validates :created_at, presence: true
+end
+
+MockImage = Struct.new(:url, :caption, keyword_init: true)
+MockCoverPhoto = Struct.new(:url, keyword_init: true)
+MockPost = Struct.new(:title, :content, :created_at, :cover_photo, :images, keyword_init: true)
+
+mock_post = MockPost.new(
+  title: 'model title',
+  content: 'model content',
+  created_at: Time.now,
+  cover_photo: MockCoverPhoto.new(url: 'https://example.com/model-cover.jpg'),
+  images: [
+    MockImage.new(url: 'https://example.com/model-1.jpg', caption: 'model image 1'),
+    MockImage.new(url: 'https://example.com/model-2.jpg', caption: 'model image 2')
+  ]
+)
+
+form = PostForm.from_model(mock_post)
+
+puts "form valid: #{form.valid?}"
+puts "title: #{form.title}"
+puts "content: #{form.content}"
+puts "cover photo url: #{form.cover_photo.url}"
+puts "images count: #{form.images.count}"
+puts "first image url: #{form.images[0].url}"
+puts "first image caption: #{form.images[0].caption}"

data/examples/model_name_example.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'voids'
+
+class PostForm < Voids::Base
+  attribute :id, :integer
+  attribute :title, :string
+end
+
+class AdminArticleForm < Voids::Base
+  model_name_for :article
+
+  attribute :id, :integer
+  attribute :title, :string
+end
+
+form1 = PostForm.new
+puts "postform model_name: #{form1.model_name}"
+puts "postform model_name.param_key: #{form1.model_name.param_key}"
+puts "postform persisted?: #{form1.persisted?}"
+puts "postform to_param: #{form1.to_param.inspect}"
+
+form2 = PostForm.new(id: 123, title: 'hello')
+puts "\npostform with id model_name: #{form2.model_name}"
+puts "postform with id persisted?: #{form2.persisted?}"
+puts "postform with id to_param: #{form2.to_param}"
+puts "postform with id to_key: #{form2.to_key.inspect}"
+
+form3 = AdminArticleForm.new
+puts "\nadminarticleform model_name: #{form3.model_name}"
+puts "adminarticleform model_name.param_key: #{form3.model_name.param_key}"

data/examples/normalization_example.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'voids'
+
+class UserForm < Voids::Base
+  attribute :email, :string
+  attribute :phone, :string
+  attribute :username, :string
+
+  normalizes :email, with: ->(email) { email.strip.downcase }
+  normalizes :phone, with: ->(phone) { phone.delete('^0-9').delete_prefix('1') }
+  normalizes :username, with: :downcase
+end
+
+puts 'email normalization'
+form = UserForm.new(email: " CRUISE-CONTROL@EXAMPLE.COM\n")
+puts "input: ' CRUISE-CONTROL@EXAMPLE.COM\\n'"
+puts "normalized: #{form.email.inspect}"
+puts
+
+puts 'phone normalization'
+form = UserForm.new(phone: '1-555-123-4567')
+puts "input: '1-555-123-4567'"
+puts "normalized: #{form.phone.inspect}"
+puts
+
+puts 'symbol normalizer'
+form = UserForm.new(username: 'JohnDoe')
+puts "input: 'JohnDoe'"
+puts "normalized: #{form.username.inspect}"
+puts
+
+puts 'idempotency test'
+form = UserForm.new(email: ' TEST@EXAMPLE.COM ')
+puts "initial: #{form.email.inspect}"
+form.email = form.email
+puts "after reassignment: #{form.email.inspect}"
+form.email = form.email
+puts "after second reassignment: #{form.email.inspect}"

data/examples/post_form_example.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'voids'
+
+class ImageForm < Voids::Base
+  attribute :url, :string
+  attribute :caption, :string
+
+  validates :url, presence: true
+end
+
+class CoverPhotoForm < Voids::Base
+  attribute :url, :string
+
+  validates :url, presence: true
+end
+
+class PostForm < Voids::Base
+  has_one :cover_photo
+  has_many :images
+
+  attribute :title, :string
+  attribute :content, :string
+  attribute :created_at, :datetime, default: -> { Time.current }
+
+  validates :title, presence: true
+  validates :content, presence: true
+  validates :created_at, presence: true
+end
+
+form = PostForm.new
+puts "empty form valid: #{form.valid?}"
+
+form = PostForm.new(
+  title: 'hello world',
+  content: 'this is content',
+  created_at: Time.now,
+  cover_photo_attributes: { url: 'https://example.com/cover.jpg' },
+  images_attributes: [
+    { url: 'https://example.com/1.jpg', caption: 'first' },
+    { url: 'https://example.com/2.jpg', caption: 'second' }
+  ]
+)
+
+puts "form with attributes valid: #{form.valid?}"
+puts "title: #{form.title}"
+puts "cover photo url: #{form.cover_photo.url}"
+puts "images count: #{form.images.count}"
+
+form = PostForm.new
+form.images.new(url: 'https://example.com/new.jpg', caption: 'new image')
+puts "form with new image count: #{form.images.count}"