superform 0.6.0 → 0.7.0

data/README.md

@@ -6,7 +6,7 @@
 
 * **Works beautifully with ERB.** Start using Superform in your existing Rails app without changing a single ERB template. All the power, zero migration pain.
 
-* **Concise field helpers.** `field(:publish_at).date`, `field(:email).email`, `field(:price).number` — intuitive methods that generate the right input types with proper validation.
+* **Concise field helpers.** `Field(:publish_at).date`, `Field(:email).email`, `Field(:price).number` — intuitive methods that generate the right input types with proper validation.
 
 * **RESTful controller helpers** Superform's `save` and `save!` methods work exactly like ActiveRecord, making controller code predictable and Rails-like.
 
@@ -16,9 +16,9 @@ Superform is a complete reimagining of Rails forms, built on solid Ruby foundati
 
 ## 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).
+Support this project and [become a Superform pro](https://beautifulruby.com/phlex/forms/introduction) by ordering the [Phlex on Rails video course](https://beautifulruby.com/phlex).
 
-[![](https://immutable.terminalwire.com/NgTt6nzO1aEnExV8j6ODuKt2iZpY74ZF8ecpUSCp4A0tXA0ErpJIS4cdMX0tQQKOWwZSl65jWnpzpgCLJThhhWtZJGr42XKt7WIi.png)](https://beautifulruby.com/phlex/forms/overview)
+[![](https://immutable.terminalwire.com/hmM9jvv7yF89frBUfjikUfRmdUsTVZ8YvXc7OnnYoERXfLJLzDcj5dFM7qdfMG2bqQLuw633Zt1gl3O7z0zKmH6k8QmifN7z0kJo.png)](https://beautifulruby.com/phlex/forms/introduction)
 
 ## Installation
 
@@ -61,7 +61,7 @@ You probably want to use the same form for creating and editing resources. In Su
 
 ```ruby
 # app/views/posts/form.rb
-class Posts::Form < Components::Form
+class Views::Posts::Form < Components::Form
   def view_template
     Field(:title).text
     Field(:body).textarea(rows: 10)
@@ -77,7 +77,7 @@ Then render this in your views:
 ```erb
 <!-- app/views/posts/new.html.erb -->
 <h1>New Post</h1>
-<%= render Posts::Form.new @post %>
+<%= render Views::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.
@@ -92,21 +92,14 @@ class PostsController < ApplicationController
 
   def create
     @post = Post.new
-    if save Posts::Form.new(@post)
+    if save Views::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
+  # ... other actions ...
 end
 ```
 
@@ -145,7 +138,7 @@ end
 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
+class Views::Posts::Form < Components::Form
   def view_template
     div(class: "form-section") do
       h2 { "Post Details" }
@@ -172,6 +165,8 @@ This gives you complete control over markup, styling, and component composition
 
 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.
 
+When building custom components, follow this convention: **positional or named keyword arguments** are for component configuration (non-HTML concerns like `value:`, `options:`, `multiple:`), and **`**kwargs`** are for HTML attributes that pass through to the rendered element. This keeps the boundary between component logic and HTML clean.
+
 ```ruby
 # ./app/components/form.rb
 class Components::Form < Superform::Rails::Form
@@ -186,7 +181,7 @@ class Components::Form < Superform::Rails::Form
   # Redefining the base Field class lets us override every field component.
   class Field < Superform::Rails::Form::Field
     def input(**attributes)
-      MyInput.new(self, attributes: attributes)
+      MyInput.new(self, **attributes)
     end
   end
 
@@ -211,8 +206,8 @@ That looks like a LOT of code, and it is, but look at how easy it is to create f
 # ./app/views/users/form.rb
 class Users::Form < Components::Form
   def view_template(&)
-    labeled field(:name).input
-    labeled field(:email).input(type: :email)
+    labeled Field(:name).input
+    labeled Field(:email).input(type: :email)
 
     submit "Sign up"
   end
@@ -227,6 +222,40 @@ Then render it from Erb.
 
 Much better!
 
+### Customizing radios and checkboxes
+
+`radios` and `checkboxes` render sensible defaults out of the box, but you can subclass them to match your design system. Override `view_template` to change the default markup — the block form still works for one-off customizations.
+
+```ruby
+class Components::Form < Superform::Rails::Form
+  class MyRadios < Superform::Rails::Components::Radios
+    def view_template(&block)
+      choices.each do |choice|
+        if block
+          yield choice
+        else
+          div(class: "radio-option") do
+            render choice.build_input(class: "radio-input")
+            label(for: DOM.join(dom.id, choice.index), class: "radio-label") do
+              plain choice.text
+            end
+          end
+        end
+      end
+    end
+  end
+
+  class Field < Field
+    def radios(*options, **attributes, &block)
+      options = enum_options if options.empty?
+      MyRadios.new(field, options:, **attributes, &block)
+    end
+  end
+end
+```
+
+Now every `Field(:status).radios` in your app gets the custom markup. Individual forms can still pass a block for one-off layouts.
+
 ## Namespaces & Collections
 
 Superform uses a different syntax for namespacing and collections than Rails, which can be a bit confusing since the same terminology is used but the application is slightly different.
@@ -259,7 +288,7 @@ class AccountForm < Superform::Rails::Form
         # Renders input with the name `account[members][0][permissions][]`,
         # `account[members][1][permissions][]`, ...
         render permission.label do
-          plain permisson.value.humanize
+          plain permission.value.humanize
           render permission.checkbox
         end
       end
@@ -285,7 +314,7 @@ By default Superform namespaces a form based on the ActiveModel model name param
 ```ruby
 class UserForm < Superform::Rails::Form
   def view_template
-    render field(:email).input
+    render Field(:email).input
   end
 end
 
@@ -301,7 +330,7 @@ To customize the form namespace, like an ActiveRecord model nested within a modu
 ```ruby
 class UserForm < Superform::Rails::Form
   def view_template
-    render field(:email).input
+    render Field(:email).input
   end
 
   def key
@@ -318,82 +347,142 @@ render UserForm.new(Admin::User.new)
 
 ## Form field guide
 
-Superform tries to strike a balance between "being as close to HTML forms as possible" and not requiring a lot of boilerplate to create forms. This example is contrived, but it shows all the different ways you can render a form.
-
-In practice, many of the calls below you'd put inside of a method. This cuts down on the number of `render` calls in your HTML code and further reduces boilerplate.
+This example builds a realistic job posting form that demonstrates every field type Superform supports. In practice you'd extract helpers to cut down on `render` calls, but this keeps things explicit so you can see exactly what's happening.
 
 ```ruby
-# Everything below is intentionally verbose!
-class SignupForm < Components::Form
+class JobPostingForm < Components::Form
   def view_template
-    # The most basic type of input, which will be autofocused.
-    Field(:name).input.focus
+    # Text input, autofocused.
+    Field(:title).input.focus
 
-    # Input field with a lot more options on it.
-    Field(:email).input(type: :email, placeholder: "We will sell this to third parties", required: true)
+    # HTML5 input helpers pass attributes straight through.
+    Field(:contact_email).email(placeholder: "hiring@company.com", required: true)
 
-    # You can put fields in a block if that's your thing.
-    field(:reason) do |f|
+    # Block form for custom layout around a field.
+    field(:description) do |f|
       div do
-        render f.label { "Why should we care about you?" }
-        render f.textarea(row: 3, col: 80)
+        render f.label { "Describe the role" }
+        render f.textarea(rows: 6, cols: 80)
       end
     end
 
-    # Let's get crazy with Selects. They can accept values as simple as 2 element arrays.
+    # Select options can be [value, label] pairs, single values, hashes, or nil
+    # for a blank option. Pass nil first to prepend a blank <option></option>.
     div do
-      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>
-        nil             # <option></option>
+      Field(:experience_level).label
+      Field(:experience_level).select(
+        nil,
+        ["junior", "Junior"],
+        ["mid", "Mid-level"],
+        ["senior", "Senior"],
+        ["lead", "Lead"]
       )
     end
 
+    # Block form gives full control — optgroups, blank options, etc.
     div do
-      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|
-          s.optgroup(label: category) do
-            s.options(sources)
+      Field(:category_id).label { "Category" }
+      Field(:category_id).select do |s|
+        s.blank_option { "Select a category..." }
+        Category.grouped_by_department.each do |department, categories|
+          s.optgroup(label: department) do
+            s.options(categories)
           end
         end
       end
     end
 
+    # Multiple select for has_many-through or array columns.
+    # Adds the HTML multiple attribute, appends [] to the field name,
+    # and includes a hidden input to handle empty submissions.
     div do
-      Field(:agreement).label { "Check this box if you agree to give us your first born child" }
-      Field(:agreement).checkbox(checked: true)
+      Field(:skill_ids).label { "Required skills" }
+      Field(:skill_ids).select(
+        Skill.select(:id, :name),
+        multiple: true
+      )
     end
 
-    render button { "Submit" }
-  end
-end
-```
+    # ActiveRecord relations work as select options too.
+    # Choices::Mapper uses the primary key as value and joins remaining
+    # attributes for the label.
+    div do
+      Field(:hiring_manager_id).label { "Hiring manager" }
+      Field(:hiring_manager_id).select(User.select(:id, :first_name, :last_name))
+    end
 
-### Upload fields
-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:
+    # Boolean checkbox — renders a hidden "0" input so unchecked state
+    # is submitted, just like Rails.
+    div do
+      Field(:remote_friendly).label { "This position is remote-friendly" }
+      Field(:remote_friendly).checkbox
+    end
 
-```ruby
-class User::ImageForm < Components::Form
-  def view_template
-    # render label
-    Field(:image).label { "Choose file" }
-    # render file input with accept attribute for png and jpeg images
-    Field(:image).input(type: "file", accept: "image/png, image/jpeg")
+    # Radio group auto-detected from a Rails enum.
+    # Given: enum :employment_type, full_time: 0, part_time: 1, contract: 2
+    # One-liner — renders <label><input type="radio"> Text</label> per choice.
+    Field(:employment_type).radios
+
+    # Block form — full control over each choice's markup.
+    fieldset do
+      legend { "Employment type" }
+      Field(:employment_type).radios do |choice|
+        choice.label {
+          choice.input
+          whitespace
+          plain choice.text   # "Full time", "Part time", "Contract"
+        }
+      end
+    end
+
+    # You can also pass explicit options to override enum detection.
+    # Accepts arrays, single values, hashes, or ActiveRecord relations.
+    # Field(:employment_type).radios("full_time" => "Full-time", ...)
+
+    # Checkbox groups. Same option formats, same Choice API.
+    # Handles name[], checked state, and unique ids automatically.
+    # One-liner:
+    Field(:benefit_ids).checkboxes(
+      [1, "Health insurance"],
+      [2, "Dental & vision"],
+      [3, "401(k)"],
+      [4, "Stock options"]
+    )
+
+    # Block form:
+    fieldset do
+      legend { "Benefits" }
+      Field(:benefit_ids).checkboxes(
+        [1, "Health insurance"],
+        [2, "Dental & vision"],
+        [3, "401(k)"],
+        [4, "Stock options"]
+      ) do |choice|
+        choice.label {
+          choice.input
+          whitespace
+          plain choice.text
+        }
+      end
+    end
+
+    # Datalist — free-text input with autocomplete suggestions.
+    # No JavaScript required. The browser handles filtering natively.
+    Field(:time_zone).datalist(*ActiveSupport::TimeZone.all.map(&:name))
+
+    # File upload (remember to set enctype on the form).
+    div do
+      Field(:job_description_pdf).label { "Upload job description" }
+      Field(:job_description_pdf).file(accept: ".pdf,.doc,.docx")
+    end
+
+    render button { "Post Job" }
   end
 end
-
-# IMPORTANT
-# When rendering the form remember to init the User::ImageForm like that
-render User::ImageForm.new(@usermodel, enctype: "multipart/form-data")
 ```
 
+Render it with `<%= render JobPostingForm.new(@job_posting) %>`. For file uploads, pass `enctype: "multipart/form-data"` to the form constructor.
+
 
 ## Extending Superforms
 
@@ -410,7 +499,7 @@ class AdminForm < Components::Form
 
   class Field < Field
     def tooltip_input(**attributes)
-      AdminInput.new(self, attributes: attributes)
+      AdminInput.new(self, **attributes)
     end
   end
 end
@@ -421,8 +510,8 @@ Then, just like you did in your Erb, you create the form:
 ```ruby
 class Admin::Users::Form < AdminForm
   def view_template(&)
-    labeled field(:name).tooltip_input
-    labeled field(:email).tooltip_input(type: :email)
+    labeled Field(:name).tooltip_input
+    labeled Field(:email).tooltip_input(type: :email)
 
     submit "Save"
   end
@@ -438,11 +527,12 @@ Superform eliminates the need to manually define strong parameters. Just include
 ```ruby
 class PostsController < ApplicationController
   include Superform::Rails::StrongParameters
+  include Views::Posts
 
   # Standard Rails CRUD with automatic strong parameters
   def create
     @post = Post.new
-    if save Posts::Form.new(@post)
+    if save Form.new(@post)
       redirect_to @post, notice: 'Post created successfully.'
     else
       render :new, status: :unprocessable_entity
@@ -451,7 +541,7 @@ class PostsController < ApplicationController
 
   def update
     @post = Post.find(params[:id])
-    if save Posts::Form.new(@post)
+    if save! Form.new(@post)
       redirect_to @post, notice: 'Post updated successfully.'
     else
       render :edit, status: :unprocessable_entity
@@ -461,7 +551,7 @@ class PostsController < ApplicationController
   # 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
+    permit Form.new(@post)  # Assigns params but doesn't save
     render :preview
   end
 end
@@ -486,6 +576,43 @@ Rails ships with a lot of great options to make forms. Many of these inspired Su
 
 Rails form helpers have lasted for almost 20 years and are super solid, but things get tricky when your application starts to take on different styles of forms. To manage it all you have to cobble together helper methods, partials, and templates. Additionally, the structure of the form then has to be expressed to the controller as strong params, forcing you to repeat yourself.
 
+Here's a checkbox group in Rails vs Superform. In Rails you need to manually wire up the field name with `[]`, track checked state against the model, generate unique ids, and point each label's `for` attribute at the right input:
+
+```erb
+<%# Rails: checkbox group for a has_many :benefits association %>
+<fieldset>
+  <legend>Benefits</legend>
+  <% Benefit.all.each do |benefit| %>
+    <%= form.check_box :benefit_ids,
+          { multiple: true,
+            checked: form.object.benefit_ids.include?(benefit.id),
+            id: "job_posting_benefit_ids_#{benefit.id}" },
+          benefit.id, nil %>
+    <%= form.label :benefit_ids, benefit.name,
+          for: "job_posting_benefit_ids_#{benefit.id}" %>
+  <% end %>
+<% end %>
+```
+
+```ruby
+# Superform — one-liner
+Field(:benefit_ids).checkboxes(Benefit.select(:id, :name))
+
+# Or with custom markup
+fieldset do
+  legend { "Benefits" }
+  Field(:benefit_ids).checkboxes(Benefit.select(:id, :name)) do |choice|
+    choice.label {
+      choice.input
+      whitespace
+      plain choice.text
+    }
+  end
+end
+```
+
+Superform handles the field name (`benefit_ids[]`), checked state, unique ids, and label targeting automatically. The same pattern works for radio groups with `radios(...)`.
+
 With Superform, you build the entire form with Ruby code, so you avoid the Erb gymnastics and helper method soup that it takes in Rails to scale up forms in an organization.
 
 ### Simple Form
@@ -514,6 +641,12 @@ https://www.ruby-toolbox.com/projects/formtastic
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+To preview example forms in your browser, run:
+
+    $ bin/preview
+
+This boots a local Rails server at http://localhost:3000 that displays all forms in the `examples/` directory. The server supports hot-reloading, so you can edit forms and refresh the page to see changes.
+
 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).
 
 ## Contributing

data/examples/basic_form.rb

@@ -0,0 +1,21 @@
+class BasicForm < ExampleForm
+  def self.description = <<~HTML
+    <p>Common input types: <code>text</code>, <code>email</code>, <code>password</code>, and <code>number</code>.</p>
+  HTML
+
+  def view_template
+    render field(:name).label
+    render field(:name).text(placeholder: "Your name")
+
+    render field(:email).label
+    render field(:email).email(placeholder: "you@example.com")
+
+    render field(:password).label
+    render field(:password).password
+
+    render field(:age).label
+    render field(:age).number(min: 0, max: 150)
+
+    render submit("Save")
+  end
+end

data/examples/checkbox_form.rb

@@ -0,0 +1,28 @@
+class CheckboxForm < ExampleForm
+  def self.description = <<~HTML
+    <p><code>checkbox</code> inputs with labels inside a fieldset.</p>
+  HTML
+
+  def view_template
+    fieldset do
+      legend { "Preferences" }
+
+      label do
+        render field(:terms_accepted).checkbox
+        plain " I accept the terms"
+      end
+
+      label do
+        render field(:subscribe).checkbox
+        plain " Subscribe to newsletter"
+      end
+
+      label do
+        render field(:featured).checkbox
+        plain " Feature this item"
+      end
+    end
+
+    render submit("Continue")
+  end
+end

data/examples/date_time_form.rb

@@ -0,0 +1,18 @@
+class DateTimeForm < ExampleForm
+  def self.description = <<~HTML
+    <p><code>date</code>, <code>time</code>, and <code>datetime</code> input types.</p>
+  HTML
+
+  def view_template
+    render field(:birth_date).label
+    render field(:birth_date).date
+
+    render field(:appointment_time).label
+    render field(:appointment_time).time
+
+    render field(:event_datetime).label
+    render field(:event_datetime).datetime
+
+    render submit("Schedule")
+  end
+end

data/examples/example_form.rb

@@ -0,0 +1,10 @@
+# Base class for example forms
+class ExampleForm < Superform::Rails::Form
+  def self.name_text
+    name.gsub(/Form$/, "").gsub(/([a-z])([A-Z])/, '\1 \2')
+  end
+
+  def self.description
+    ""
+  end
+end

data/examples/select_form.rb

@@ -0,0 +1,26 @@
+class SelectForm < ExampleForm
+  def self.description = <<~HTML
+    <p><code>select</code> dropdowns with various option formats.</p>
+  HTML
+
+  COUNTRIES = [
+    ["United States", "us"],
+    ["Canada", "ca"],
+    ["United Kingdom", "uk"],
+    ["Germany", "de"],
+    ["Japan", "jp"]
+  ].freeze
+
+  def view_template
+    render field(:country).label
+    render field(:country).select(options: COUNTRIES, include_blank: "Choose...")
+
+    render field(:priority).label
+    render field(:priority).select(options: %w[Low Medium High])
+
+    render field(:quantity).label
+    render field(:quantity).select(options: (1..10).to_a)
+
+    render submit("Submit")
+  end
+end

data/examples/special_inputs_form.rb

@@ -0,0 +1,23 @@
+class SpecialInputsForm < ExampleForm
+  def self.name_text = "Special Inputs"
+
+  def self.description = <<~HTML
+    <p>HTML5 input types: <code>color</code>, <code>range</code>, <code>search</code>, and <code>file</code>.</p>
+  HTML
+
+  def view_template
+    render field(:favorite_color).label
+    render field(:favorite_color).color
+
+    render field(:volume).label
+    render field(:volume).range(min: 0, max: 100, step: 10)
+
+    render field(:search_query).label
+    render field(:search_query).search(placeholder: "Search...")
+
+    render field(:avatar).label
+    render field(:avatar).file(accept: "image/*")
+
+    render submit("Apply")
+  end
+end

data/examples/textarea_form.rb

@@ -0,0 +1,15 @@
+class TextareaForm < ExampleForm
+  def self.description = <<~HTML
+    <p>Text input and <code>textarea</code> for longer content.</p>
+  HTML
+
+  def view_template
+    render field(:title).label
+    render field(:title).text(placeholder: "Post title")
+
+    render field(:body).label
+    render field(:body).textarea(rows: 6, placeholder: "Write your content...")
+
+    render submit("Publish")
+  end
+end

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

@@ -1,22 +1,40 @@
 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
+    # Extend the Field class to add your own custom helpers.
+    class Field < self::Field
+      # # Overide base form helpers for small modifications, like injecting
+      # # default classes or styles.
+      # def input(class: nil, **)
+      #   super(class: ["border p-2", grab(class:)], **)
+      # end
+      #
+      # # Create custom field helpers that may be accessed via `fied(:email).my_input`
+      # def required_email(**)
+      #   input(type: "email", required: true, **)
+      # end
+      #
+      # # Return your own component if you're doing more complicated things.
+      # def autocomplete(**attributes)
+      #   Components::Autocomplete.new(field, **attributes)
+      # end
     end
 
     def around_template(&)
       super do
+        # Renders error messages if there are any validation errors on the model
         error_messages
+        # Renders the contents of the form from `view_template` or the block passed
+        # the #render method.
         yield if block_given?
+        # Renders the submit button for the form.
         submit
       end
     end
 
+    # This is needed for the `error_messages`
+    include Phlex::Rails::Helpers::Pluralize
+
+    # Displays error messages for the form's model if there are any validation errors.
     def error_messages
       if model.errors.any?
         div(style: "color: red;") do
@@ -29,5 +47,13 @@ module Components
         end
       end
     end
+
+    # Wraps a form field and its label in a div for layout purposes.
+    def row(component)
+      div do
+        render component.field.label(style: "display: block;")
+        render component
+      end
+    end
   end
 end