superform 0.5.0 → 0.6.0

data/README.md

@@ -1,17 +1,25 @@
 # Superform
 
-Superform aims to be the best way to build forms in Rails applications. Here's what it does differently.
+**The best Rails form library.** Whether you're using ERB, HAML, or Phlex, Superform makes building forms delightful.
 
-* **Everything is a component.** Superform is built on top of [Phlex](https://phlex.fun), so every bit of HTML in the form can be customized to your precise needs. Use it with your own CSS Framework or go crazy customizing every last bit of TailwindCSS.
+* **No more strong parameters headaches.** Add a field to your form and it automatically gets permitted. Never again wonder why your new field isn't saving. Superform handles parameter security for you.
 
-* **Automatic strong parameters.** Superform automatically permits form fields so you don't have to facepalm yourself after adding a field, wondering why it doesn't persist, only to realize you forgot to add the parameter to your controller. No more! Superform was architected with safety & security in mind, meaning it can automatically permit your form parameters.
+* **Works beautifully with ERB.** Start using Superform in your existing Rails app without changing a single ERB template. All the power, zero migration pain.
 
-* **Compose complex forms with Plain 'ol Ruby Objects.** Superform is built on top of POROs, so you can easily compose classes, modules, & ruby code together to create complex forms. You can even extend forms to create new forms with a different look and feel.
+* **Concise field helpers.** `field(:publish_at).date`, `field(:email).email`, `field(:price).number` — intuitive methods that generate the right input types with proper validation.
 
-It's a complete rewrite of Rails form's internals that's inspired by Reactive component design patterns.
+* **RESTful controller helpers** Superform's `save` and `save!` methods work exactly like ActiveRecord, making controller code predictable and Rails-like.
+
+Superform is a complete reimagining of Rails forms, built on solid Ruby foundations with modern component architecture under the hood.
 
 [![Maintainability](https://api.codeclimate.com/v1/badges/0e4dfe2a1ece26e3a59e/maintainability)](https://codeclimate.com/github/rubymonolith/superform/maintainability) [![Ruby](https://github.com/rubymonolith/superform/actions/workflows/main.yml/badge.svg)](https://github.com/rubymonolith/superform/actions/workflows/main.yml)
 
+## Video course
+
+Support this project and [become a Superform pro](https://beautifulruby.com/phlex/forms/overview) by ordering the [Phlex on Rails video course](https://beautifulruby.com/phlex).
+
+[![](https://immutable.terminalwire.com/NgTt6nzO1aEnExV8j6ODuKt2iZpY74ZF8ecpUSCp4A0tXA0ErpJIS4cdMX0tQQKOWwZSl65jWnpzpgCLJThhhWtZJGr42XKt7WIi.png)](https://beautifulruby.com/phlex/forms/overview)
+
 ## Installation
 
 Add to the Rails application's Gemfile by executing:
@@ -26,49 +34,164 @@ This will install both Phlex Rails and Superform.
 
 ## Usage
 
-Superform streamlines the development of forms on Rails applications by making everything a component.
+### Start with inline forms in your ERB templates
+
+Superform works instantly in your existing Rails ERB templates. Here's what a form for a blog post might look like:
+
+```erb
+<!-- app/views/posts/new.html.erb -->
+<h1>New Post</h1>
+
+<%= render Components::Form.new @post do
+  it.Field(:title).text
+  it.Field(:body).textarea
+  it.Field(:publish_at).date
+  it.Field(:featured).checkbox
+  it.submit "Create Post"
+end %>
+```
 
-After installing, create a form in `app/views/*/form.rb`. For example, a form for a `Post` resource might look like this.
+The form automatically generates proper Rails form tags, includes CSRF tokens, and handles validation errors.
+
+Notice anything missing? Superform doesn't need `<% %>` tags around every single line, unlike all other Rails form helpers.
+
+### Extract inline forms to dedicated classes to use in other views
+
+You probably want to use the same form for creating and editing resources. In Superform, you extract forms into their own Ruby classes right along with your views.
 
 ```ruby
-# ./app/views/posts/form.rb
-class Posts::Form < ApplicationForm
-  def template(&)
-    row field(:title).input
-    row field(:body).textarea
-    row field(:blog).select Blog.select(:id, :title)
+# app/views/posts/form.rb
+class Posts::Form < Components::Form
+  def view_template
+    Field(:title).text
+    Field(:body).textarea(rows: 10)
+    Field(:publish_at).date
+    Field(:featured).checkbox
+    submit
   end
 end
 ```
 
-Then render it in your templates. Here's what it looks like from an Erb file.
+Then render this in your views:
 
 ```erb
-<h1>New post</h1>
+<!-- app/views/posts/new.html.erb -->
+<h1>New Post</h1>
 <%= render Posts::Form.new @post %>
 ```
 
+Cool, but you're about to score a huge benefit from extracting forms into their own Ruby classes with automatic strong parameters.
+
+### Automatically permit strong parameters with form classes
+
+Include `Superform::Rails::StrongParameters` in your controllers for automatic parameter handling:
+
+```ruby
+class PostsController < ApplicationController
+  include Superform::Rails::StrongParameters
+
+  def create
+    @post = Post.new
+    if save Posts::Form.new(@post)
+      redirect_to @post, notice: 'Post created!'
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    @post = Post.find(params[:id])
+    if save Posts::Form.new(@post)
+      redirect_to @post, notice: 'Post updated!'
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+The `save` method automatically:
+- Permits only the parameters defined in your form
+- Assigns them to your model
+- Attempts to save the model
+- Returns `true` if successful, `false` if validation fails
+
+Use `save!` for the bang version that raises exceptions on validation failure or `permit` if you want to assign parameters to a model without saving it.
+
+### Concise HTML5 form helpers
+
+Superform includes helpers for all HTML5 input types:
+
+```ruby
+class UserForm < Components::Form
+  def view_template
+    Field(:email).email           # type="email"
+    Field(:password).password     # type="password"
+    Field(:website).url           # type="url"
+    Field(:phone).tel             # type="tel"
+    Field(:age).number(min: 18)   # type="number"
+    Field(:birthday).date         # type="date"
+    Field(:appointment).datetime  # type="datetime-local"
+    Field(:favorite_color).color  # type="color"
+    Field(:bio).textarea(rows: 5)
+    Field(:terms).checkbox
+    submit
+  end
+end
+```
+
+### Works great with Phlex
+
+Superform was built from the ground-up using Phlex components, which means you'll feel right at home using it with your existing Phlex views and components.
+
+```ruby
+class Posts::Form < Components::Form
+  def view_template
+    div(class: "form-section") do
+      h2 { "Post Details" }
+      Field(:title).text(class: "form-control")
+      Field(:body).textarea(class: "form-control", rows: 10)
+    end
+
+    div(class: "form-section") do
+      h2 { "Publishing" }
+      Field(:publish_at).date(class: "form-control")
+      Field(:featured).checkbox(class: "form-check-input")
+    end
+
+    div(class: "form-actions") do
+      submit "Save Post", class: "btn btn-primary"
+    end
+  end
+end
+```
+
+This gives you complete control over markup, styling, and component composition while maintaining all the strong parameter and validation benefits.
+
 ## Customization
 
-Superforms are built out of [Phlex components](https://www.phlex.fun/html/components/). The method names correspeond with the HTML tag, its arguments are attributes, and the blocks are the contents of the tag.
+Superforms are built out of [Phlex components](https://www.phlex.fun/html/components/). The method names correspond with the HTML tag, its arguments are attributes, and the blocks are the contents of the tag.
 
 ```ruby
-# ./app/views/forms/application_form.rb
-class ApplicationForm < Superform::Rails::Form
-  class MyInputComponent < Superform::Rails::Components::InputComponent
-    def template(&)
+# ./app/components/form.rb
+class Components::Form < Superform::Rails::Form
+  class MyInput < Superform::Rails::Components::Input
+    def view_template(&)
       div class: "form-field" do
         input(**attributes)
       end
     end
   end
 
+  # Redefining the base Field class lets us override every field component.
   class Field < Superform::Rails::Form::Field
     def input(**attributes)
-      MyInputComponent.new(self, attributes: attributes)
+      MyInput.new(self, attributes: attributes)
     end
   end
 
+  # Here we make a simple helper to make our syntax shorter. Given a field it
+  # will also render its label.
   def labeled(component)
     div class: "form-row" do
       render component.field.label
@@ -86,8 +209,8 @@ That looks like a LOT of code, and it is, but look at how easy it is to create f
 
 ```ruby
 # ./app/views/users/form.rb
-class Users::Form < ApplicationForm
-  def template(&)
+class Users::Form < Components::Form
+  def view_template(&)
     labeled field(:name).input
     labeled field(:email).input(type: :email)
 
@@ -112,23 +235,23 @@ Consider a form for an account that lets people edit the names and email of the
 
 ```ruby
 class AccountForm < Superform::Rails::Form
-  def template
+  def view_template
     # Account#owner returns a single object
     namespace :owner do |owner|
       # Renders input with the name `account[owner][name]`
-      render owner.field(:name).input
+      owner.Field(:name).text
       # Renders input with the name `account[owner][email]`
-      render owner.field(:email).input(type: :email)
+      owner.Field(:email).email
     end
 
     # Account#members returns a collection of objects
     collection(:members).each do |member|
       # Renders input with the name `account[members][0][name]`,
       # `account[members][1][name]`, ...
-      render member.field(:name).input
+      member.Field(:name).input
       # Renders input with the name `account[members][0][email]`,
       # `account[members][1][email]`, ...
-      render member.field(:email).input(type: :email)
+      member.Field(:email).input(type: :email)
 
       # Member#permissions returns an array of values like
       # ["read", "write", "delete"].
@@ -161,7 +284,7 @@ By default Superform namespaces a form based on the ActiveModel model name param
 
 ```ruby
 class UserForm < Superform::Rails::Form
-  def template
+  def view_template
     render field(:email).input
   end
 end
@@ -177,10 +300,10 @@ To customize the form namespace, like an ActiveRecord model nested within a modu
 
 ```ruby
 class UserForm < Superform::Rails::Form
-  def template
+  def view_template
     render field(:email).input
   end
-  
+
   def key
     "user"
   end
@@ -201,26 +324,26 @@ In practice, many of the calls below you'd put inside of a method. This cuts dow
 
 ```ruby
 # Everything below is intentionally verbose!
-class SignupForm < ApplicationForm
-  def template
+class SignupForm < Components::Form
+  def view_template
     # The most basic type of input, which will be autofocused.
-    render field(:name).input.focus
+    Field(:name).input.focus
 
     # Input field with a lot more options on it.
-    render field(:email).input(type: :email, placeholder: "We will sell this to third parties", required: true)
+    Field(:email).input(type: :email, placeholder: "We will sell this to third parties", required: true)
 
     # You can put fields in a block if that's your thing.
-    render field(:reason) do |f|
+    field(:reason) do |f|
       div do
-        f.label { "Why should we care about you?" }
-        f.textarea(row: 3, col: 80)
+        render f.label { "Why should we care about you?" }
+        render f.textarea(row: 3, col: 80)
       end
     end
 
     # Let's get crazy with Selects. They can accept values as simple as 2 element arrays.
     div do
-      render field(:contact).label { "Would you like us to spam you to death?" }
-      render field(:contact).select(
+      Field(:contact).label { "Would you like us to spam you to death?" }
+      Field(:contact).select(
         [true, "Yes"],  # <option value="true">Yes</option>
         [false, "No"],  # <option value="false">No</option>
         "Hell no",      # <option value="Hell no">Hell no</option>
@@ -229,8 +352,10 @@ class SignupForm < ApplicationForm
     end
 
     div do
-      render field(:source).label { "How did you hear about us?" }
-      render field(:source).select do |s|
+      Field(:source).label { "How did you hear about us?" }
+      Field(:source).select do |s|
+        # Renders a blank option.
+        s.blank_option
         # Pretend WebSources is an ActiveRecord scope with a "Social" category that has "Facebook, X, etc"
         # and a "Search" category with "AltaVista, Yahoo, etc."
         WebSources.select(:id, :name).group_by(:category) do |category, sources|
@@ -242,8 +367,8 @@ class SignupForm < ApplicationForm
     end
 
     div do
-      render field(:agreement).label { "Check this box if you agree to give us your first born child" }
-      render field(:agreement).checkbox(checked: true)
+      Field(:agreement).label { "Check this box if you agree to give us your first born child" }
+      Field(:agreement).checkbox(checked: true)
     end
 
     render button { "Submit" }
@@ -255,12 +380,12 @@ end
 If you want to add file upload fields to your form you will need to initialize your form with the `enctype` attribute set to `multipart/form-data` as shown in the following example code:
 
 ```ruby
-class User::ImageForm < ApplicationForm
-  def template
+class User::ImageForm < Components::Form
+  def view_template
     # render label
-    render field(:image).label { "Choose file" }
+    Field(:image).label { "Choose file" }
     # render file input with accept attribute for png and jpeg images
-    render field(:image).input(type: "file", accept: "image/png, image/jpeg")
+    Field(:image).input(type: "file", accept: "image/png, image/jpeg")
   end
 end
 
@@ -275,9 +400,9 @@ render User::ImageForm.new(@usermodel, enctype: "multipart/form-data")
 The best part? If you have forms with a completely different look and feel, you can extend the forms just like you would a Ruby class:
 
 ```ruby
-class AdminForm < ApplicationForm
-  class AdminInput < ApplicationComponent
-    def template(&)
+class AdminForm < Components::Form
+  class AdminInput < Components::Base
+    def view_template(&)
       input(**attributes)
       small { admin_tool_tip_for field.key }
     end
@@ -295,7 +420,7 @@ Then, just like you did in your Erb, you create the form:
 
 ```ruby
 class Admin::Users::Form < AdminForm
-  def template(&)
+  def view_template(&)
     labeled field(:name).tooltip_input
     labeled field(:email).tooltip_input(type: :email)
 
@@ -304,41 +429,50 @@ class Admin::Users::Form < AdminForm
 end
 ```
 
-Since Superforms are just Ruby objects, you can organize them however you want. You can keep your view component classes embedded in your Superform file if you prefer for everything to be in one place, keep the forms in the `app/views/forms/*.rb` folder and the components in `app/views/forms/**/*_component.rb`, use Ruby's `include` and `extend` features to modify different form classes, or put them in a gem and share them with an entire organization or open source community. It's just Ruby code!
+Since Superforms are just Ruby objects, you can organize them however you want. You can keep your view component classes embedded in your Superform file if you prefer for everything to be in one place, keep the forms in the `app/components/forms/*.rb` folder and the components in `app/components/forms/**/*_component.rb`, use Ruby's `include` and `extend` features to modify different form classes, or put them in a gem and share them with an entire organization or open source community. It's just Ruby code!
 
 ## Automatic strong parameters
 
-Guess what? Superform eliminates the need for Strong Parameters in Rails by assigning the values of the `params` hash _through_ your form via the `assign` method. Here's what it looks like.
+Superform eliminates the need to manually define strong parameters. Just include `Superform::Rails::StrongParameters` in your controllers and use the `save`, `save!`, and `permit` methods:
 
 ```ruby
 class PostsController < ApplicationController
   include Superform::Rails::StrongParameters
 
+  # Standard Rails CRUD with automatic strong parameters
   def create
-    @post = assign params.require(:post), to: Posts::Form.new(Post.new)
-
-    if @post.save
-      # Success path
+    @post = Post.new
+    if save Posts::Form.new(@post)
+      redirect_to @post, notice: 'Post created successfully.'
     else
-      # Error path
+      render :new, status: :unprocessable_entity
     end
   end
 
   def update
     @post = Post.find(params[:id])
-
-    assign params.require(:post), to: Posts::Form.new(@post)
-
-    if @post.save
-      # Success path
+    if save Posts::Form.new(@post)
+      redirect_to @post, notice: 'Post updated successfully.'
     else
-      # Error path
+      render :edit, status: :unprocessable_entity
     end
   end
+
+  # For cases where you want to assign params without saving
+  def preview
+    @post = Post.new
+    permit Posts::Form.new(@post)  # Assigns params but doesn't save
+    render :preview
+  end
 end
 ```
 
-How does it work? An instance of the form is created, then the hash is assigned to it. If the params include data outside of what a form accepts, it will be ignored.
+**How it works:** Superform automatically permits only the parameters that correspond to fields defined in your form. Attempts to mass-assign other parameters are safely ignored, protecting against parameter pollution attacks.
+
+**Available methods:**
+- `save(form)` - Assigns permitted params and saves the model, returns `true`/`false`
+- `save!(form)` - Same as `save` but raises exception on validation failure
+- `permit(form)` - Assigns permitted params without saving, returns the model
 
 ## Comparisons
 

data/SPEC_STYLE_GUIDE.md

@@ -0,0 +1,146 @@
+# Spec Style Guide
+
+This document outlines the preferred testing patterns for Superform. Follow these patterns to maintain consistency and readability across the test suite.
+
+## Generator Testing
+
+### ✅ Preferred Pattern
+
+Use integration-style testing that actually runs the generator:
+
+```ruby
+RSpec.describe SomeGenerator, type: :generator do
+  let(:destination_root) { Dir.mktmpdir }
+  let(:generator) { described_class.new([], {}, { destination_root: destination_root }) }
+
+  before do
+    FileUtils.mkdir_p(destination_root)
+    allow(Rails).to receive(:root).and_return(Pathname.new(destination_root))
+  end
+
+  after do
+    FileUtils.rm_rf(destination_root) if File.exist?(destination_root)
+  end
+
+  context "when dependencies are met" do
+    before do
+      allow(generator).to receive(:gem_in_bundle?).with("some-gem").and_return(true)
+    end
+
+    it "creates the expected file" do
+      generator.invoke_all
+      expect(File.exist?(File.join(destination_root, "path/to/file.rb"))).to be true
+    end
+
+    describe "generated file" do
+      subject { File.read(File.join(destination_root, "path/to/file.rb")) }
+      
+      before { generator.invoke_all }
+      
+      it { is_expected.to include("class SomeClass") }
+      it { is_expected.to include("def some_method") }
+    end
+  end
+end
+```
+
+### ❌ Avoid This Pattern
+
+Don't unit test individual generator methods in isolation:
+
+```ruby
+# DON'T DO THIS
+it "creates file with correct content" do
+  generator.create_some_file
+  
+  content = File.read(file_path)
+  expect(content).to include("class SomeClass")
+  expect(content).to include("def some_method") 
+  expect(content).to include("def another_method")
+  # ... more expectations
+end
+```
+
+## File Content Testing
+
+### ✅ Use Subject Blocks
+
+When testing generated file content, use `subject` blocks with `is_expected` matchers:
+
+```ruby
+describe "generated file" do
+  subject { File.read(file_path) }
+  
+  before { run_generator_or_setup }
+  
+  it { is_expected.to include("essential content") }
+  it { is_expected.to include("other essential content") }
+end
+```
+
+### ❌ Don't Repeat File Reading
+
+Avoid reading the same file multiple times in different tests:
+
+```ruby
+# DON'T DO THIS
+it "includes class definition" do
+  content = File.read(file_path)
+  expect(content).to include("class SomeClass")
+end
+
+it "includes method definition" do  
+  content = File.read(file_path)  # Reading same file again
+  expect(content).to include("def some_method")
+end
+```
+
+## Test Focus
+
+### ✅ Test What Matters
+
+Focus on essential functionality, not implementation details:
+
+```ruby
+# Test the important stuff
+it { is_expected.to include("class Base < Superform::Rails::Form") }
+it { is_expected.to include("def row(component)") }
+```
+
+### ❌ Don't Over-Test
+
+Avoid brittle, line-by-line assertions:
+
+```ruby
+# DON'T DO THIS - too brittle
+expect(lines[0]).to eq("module Components")
+expect(lines[1]).to eq("  module Forms") 
+expect(lines[2]).to eq("    class Base < Superform::Rails::Form")
+```
+
+## Test Structure
+
+### ✅ Good Test Organization
+
+- Use contexts to group related scenarios
+- Use descriptive test names
+- Keep tests focused and minimal
+- Use `before` blocks to set up common state
+
+### ✅ Integration Over Unit
+
+- Test generators by actually running them
+- Test the user experience, not internal methods
+- Mock external dependencies, not internal logic
+
+## Key Principles
+
+1. **Integration over Unit**: Test how components work together, not in isolation
+2. **User Experience**: Test what users actually do and see  
+3. **Essential over Exhaustive**: Test what matters, not every edge case
+4. **Readable over Clever**: Clear, simple tests are better than complex ones
+5. **DRY but Clear**: Eliminate repetition without sacrificing readability
+
+## Example: Good Generator Spec
+
+See `spec/generators/superform/install_generator_spec.rb` for a complete example of these patterns in action.

data/lib/generators/superform/install/USAGE

@@ -1,8 +1,12 @@
 Description:
-    Installs Phlex Rails and Superform
+    Installs Superform with proper component structure
 
 Example:
     bin/rails generate superform:install
 
     This will create:
-        app/views/forms/application_form.rb
+        app/components/form.rb
+
+    Prerequisites:
+        phlex-rails must be installed. If not installed, run:
+        bundle add phlex-rails

data/lib/generators/superform/install/install_generator.rb

@@ -3,31 +3,20 @@ require "bundler"
 class Superform::InstallGenerator < Rails::Generators::Base
   source_root File.expand_path("templates", __dir__)
 
-  APPLICATION_CONFIGURATION_PATH = Rails.root.join("config/application.rb")
-
-  def install_phlex_rails
-    return if gem_in_bundle? "phlex-rails"
-
-    gem "phlex-rails"
-    generate "phlex:install"
-  end
-
-  def autoload_components
-    return unless APPLICATION_CONFIGURATION_PATH.exist?
-
-    inject_into_class(
-      APPLICATION_CONFIGURATION_PATH,
-      "Application",
-      %(    config.autoload_paths << "\#{root}/app/views/forms"\n)
-    )
+  def check_phlex_rails_dependency
+    unless gem_in_bundle?("phlex-rails")
+      say "ERROR: phlex-rails is not installed. Please run 'bundle add phlex-rails' first.", :red
+      exit 1
+    end
   end
 
   def create_application_form
-    template "application_form.rb", Rails.root.join("app/views/forms/application_form.rb")
+    template "base.rb", Rails.root.join("app/components/form.rb")
   end
 
   private
-    def gem_in_bundle?(gem_name)
-      Bundler.load.specs.any? { |spec| spec.name == gem_name }
-    end
-end
+
+  def gem_in_bundle?(gem_name)
+    Bundler.load.specs.any? { |spec| spec.name == gem_name }
+  end
+end

data/lib/generators/superform/install/templates/base.rb

@@ -0,0 +1,33 @@
+module Components
+  class Form < Superform::Rails::Form
+    include Phlex::Rails::Helpers::Pluralize
+
+    def row(component)
+      div do
+        render component.field.label(style: "display: block;")
+        render component
+      end
+    end
+
+    def around_template(&)
+      super do
+        error_messages
+        yield if block_given?
+        submit
+      end
+    end
+
+    def error_messages
+      if model.errors.any?
+        div(style: "color: red;") do
+          h2 { "#{pluralize model.errors.count, "error"} prohibited this post from being saved:" }
+          ul do
+            model.errors.each do |error|
+              li { error.full_message }
+            end
+          end
+        end
+      end
+    end
+  end
+end