composable-form 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28b26e4d94280e1988cd68bb4e6de1a519450b7b81b8ec084256126a251a35e6
-  data.tar.gz: c5218ef7595dd0cd7c7af9adf2b67bd13a1d27a61143c1a8a52229595bfc00f8
+  metadata.gz: f24c4de19b32a5c86c1e1d27fcadda201048976bf7301adfb42277e6b02e5e52
+  data.tar.gz: 1c4390383698b86e1e233d5bd11b829e6651a1982de360abf6c00952298be6d8
 SHA512:
-  metadata.gz: 7a7666284692dd67679b28375c621ea1d86536440071d29fc5226152ab4ad2b34237d0a7ef9c213aaa8ddf3263c62c9577736adf0de4b2073e2360615204b943
-  data.tar.gz: cbfac93763553e3cfd59b1a4aee4c4f1c97e30fb80ed832d3438ba8248eaa8daa2dd19f6372d4255822e825861b8bd7568e65a318b5f6dd223ad6cb658cfb10a
+  metadata.gz: 05f8b36572ae20f88eca269941ccc8cb9e82efba73e8927d3e310e69c494def537366810c7dee9429ec696915b29b09b330a9be8a1599a4fb3192c7620b1114e
+  data.tar.gz: 03c6522b0db1b8bd1836e5e9d0a247bab3198a885ff78471b7e7f608755562992ccd4531c6a9b47bf6ce3747d0a30fcf8937df1e282b20c0925cbe96d9fd3e82

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+- Prepend the command wrapper once to preserve results in nested subclasses.
+- Mark aborted callbacks as failures and document persistence/model naming.
+- Add behavioral tests with complete line/branch coverage.
+
 ## [0.0.1] - 2022-01-24
 
 - Initial release

data/README.md

@@ -1,43 +1,166 @@
-# Composable::Form
+# composable-form
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/composable/form`. To experiment with that code, run `bin/console` for an interactive prompt.
+Rails form objects combining ActiveModel validation, composed record persistence,
+callbacks and model naming. Requires Ruby 3.2+ and ActiveModel/ActiveSupport 7.2+.
+Install `gem "composable-form"`; require `composable/form`.
 
-TODO: Delete this and the text above, and describe your gem
+## Map a form to a record
 
-## Installation
+```ruby
+require "composable/form"
+
+class ProjectForm < Composable::Form::Command
+  attribute :name, type: :string
+  validates :name, presence: true
+
+  composable :project, model: Project do
+    sync :name
+  end
+end
+
+project = Project.new(name: "Initial")
+form = ProjectForm.new(project: project, name: "Updated")
+form.call
+form.success? # => true
+form.project.name # => "Updated"
+```
 
-Add this line to your application's Gemfile:
+The application provides the `Project` ActiveRecord model and its table.
+`model: Project` supplies model naming and delegates `id`, `persisted?` and
+`new_record?` to `project`. Forms without a model mapping report `persisted?` as
+false and `new_record?` as true. This integration does not delegate `public_id` or
+`to_param`, or authorize the underlying record.
+
+In a controller, load an authorized record first, then pass explicit strong
+parameters:
 
 ```ruby
-gem 'composable-form'
+form = ProjectForm.call(
+  params.require(:project).permit(:name).to_h.merge(project: authorized_project)
+)
 ```
 
-And then execute:
+Use `form_with model: form` in the Rails view. On failure, render the form with
+status `:unprocessable_entity` and display its errors.
+
+## Persistence and callbacks
+
+The order is: validate form, enter `save` callbacks, synchronize and save eligible
+records, execute the form's `save`, finish callbacks. Override private `save` to
+return a result or perform additional work. Without an override its result is
+nil. `before_save`, `around_save` and `after_save` use the ActiveModel callback API.
+An aborted chain or a `false` result records failure.
+
+`.call` returns the form; `.call!` raises on errors. Record validation errors are
+copied without modifying the record's errors. Unhandled exceptions propagate.
+`rescue_from` may translate expected exceptions into form errors.
+
+Shared-connection record writes roll back when an exception escapes the
+transaction. Adding errors alone does not roll back writes; callbacks finishing
+after the transaction are not part of that transaction. Separate database
+connections do not guarantee distributed atomicity.
 
-    $ bundle install
+See [core](../composable-core/README.md) for conditional composition, input
+precedence and typing, and [testing](../docs/testing.md) for coverage requirements.
 
-Or install it yourself as:
+## Connect a controller and view
 
-    $ gem install composable-form
+Assume the application provides `current_account.projects` as an authorized
+association. Load the record through that association before building the form:
 
-## Usage
+```ruby
+class ProjectsController < ApplicationController
+  def edit
+    project = current_account.projects.find(params[:id])
+    @form = ProjectForm.new(project: project)
+  end
+
+  def update
+    project = current_account.projects.find(params[:id])
+    @form = ProjectForm.call(
+      project_params.to_h.merge(project: project)
+    )
+
+    if @form.success?
+      redirect_to project_path(project), notice: "Project updated"
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def project_params
+    params.require(:project).permit(:name)
+  end
+end
+```
 
-TODO: Write usage instructions here
+Because `model: Project` gives the form the model's naming, the generated fields
+use the `project` parameter key. Specify the route explicitly:
 
-## Development
+```erb
+<%= form_with model: @form, url: project_path(@form.project), method: :patch do |f| %>
+  <% @form.errors.full_messages.each do |message| %>
+    <p><%= message %></p>
+  <% end %>
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+  <%= f.label :name %>
+  <%= f.text_field :name %>
+  <%= f.submit "Save" %>
+<% end %>
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Rename mappings and conditionally write fields
 
-## Contributing
+Assume `Project` also has a `description` column. This form exposes a different
+name for that field and writes it only when the caller explicitly opts in:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jairovm/composables. 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/jairovm/composables/tree/main/CODE_OF_CONDUCT.md).
+```ruby
+class ProjectDetailsForm < Composable::Form::Command
+  attribute :name, :summary, type: :string
+  attribute :update_summary, type: :boolean, default: false
+  validates :name, presence: true
+
+  composable :project, model: Project do
+    sync :name
+    sync :summary, to: :description, if: :update_summary?
+  end
+
+  private
+
+  def save
+    project
+  end
+end
+
+form = ProjectDetailsForm.new(project: project)
+form.summary # => the project's current description
+
+operation = ProjectDetailsForm.call(
+  project: project, name: "Revised", summary: "New description",
+  update_summary: true
+)
+operation.result # => project, when persistence succeeds
+```
 
-## License
+The condition controls writes, not the initial read from the record. Treat
+`update_summary` as application policy input: do not permit it from a browser
+unless the user is allowed to make that decision. Implement `save` rather than
+redefining `call`, so validation, composition and command wrapping remain active.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Normalize input before saving
 
-## Code of Conduct
+Callbacks run after form validation. For a value that must be normalized before
+validation, normalize in its setter rather than a `before_save` callback:
 
-Everyone interacting in the Composable::Form project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jairovm/composables/tree/main/CODE_OF_CONDUCT.md).
+```ruby
+class NormalizedProjectForm < ProjectForm
+  def name=(value)
+    super(value&.strip)
+  end
+end
+
+form = NormalizedProjectForm.new(project: project, name: "  Example  ")
+form.name # => "Example"
+```

data/lib/composable/form/command.rb

@@ -8,14 +8,10 @@ module Composable
       include Core::AttributeDSL
       include Core::ComposableDSL
       include Core::Callbacks
+      prepend Core::Command
       include ActiveModel::Conversion
 
       class << self
-        def inherited(subclass)
-          super
-          subclass.prepend(Core::Command)
-        end
-
         def composable(attribute, model: nil, **options, &block)
           super(attribute, **options, &block)
 
@@ -32,9 +28,11 @@ module Composable
       def call
         return unless valid?
 
-        run_callbacks :save do
+        completed = run_callbacks :save do
           @result = save_composables { save }
         end
+        errors.add(:base, :invalid) if completed == false
+        @result
       end
 
       def persisted?

data/lib/composable/form/gem_version.rb

@@ -10,7 +10,7 @@ module Composable
     module VERSION
       MAJOR = 0
       MINOR = 0
-      TINY  = 13
+      TINY  = 14
       PRE   = nil
 
       STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: composable-form
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Jairo Vazquez
 bindir: exe
 cert_chain: []
-date: 2025-08-09 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: composable-core
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.13
+        version: 0.0.14
 description: Form composable object to work with Rails ActionView forms
 email:
 - jairovm20@gmail.com
@@ -51,7 +51,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="