superform 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 764fb4731b8ae1977a1e05ce0410302e5f29f3c008c4e0326f9b3f852118cb37
-  data.tar.gz: 6d7887d4b7b3bbf2af8ebfe7e675a155061e4982231d3f52caefd7a5e4c4c85d
+  metadata.gz: 5daa39c7a090d229f2175c5214e69ae17c586738ff7b64c9c8c4d7745f52e08f
+  data.tar.gz: 7d5b2fa66f1230f5f7efdbdc2a97fef97fb1ad5c069dc1331a685cfd4cee474b
 SHA512:
-  metadata.gz: edb3acf775edcaacb269b0aff7200d6bfd22d2c5701eb7dd0c96149bbc515acf33b77f586809ac574520a4330c1ed1acbe304e8c54d60a2b219e28b72179321b
-  data.tar.gz: e2b69ed000da6eeddeb3a47f664abfe052bbd85ae0e5649d23131b134d5d68acc9032fd4660260207540724c5fa10b85d6c6b4609484849e7c480a9fbd90bae1
+  metadata.gz: f8b014e3dceb150d9e17e294794370a967f8bec8630a37219e20c3fbb3d4fbdac89dbd5a4beb91829f4c3e74155d607fee303e71600f16d6d5a8cbb3c100ebc1
+  data.tar.gz: debd7cf51bdea3de105412ceece2bea44f074acb713eeffc786ca1f6c56e7323f54cec2b8a12b8b36172e3c3b4b74a071738d2978bee5e15a63bf36692f7dde7

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    superform (0.4.0)
+    superform (0.4.1)
       phlex-rails (~> 1.0)
+      zeitwerk (~> 2.6)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -36,6 +36,7 @@ class Posts::Form < ApplicationForm
   def template(&)
     row field(:title).input
     row field(:body).textarea
+    row field(:blog).select Blog.select(:id, :title)
   end
 end
 ```
@@ -106,6 +107,64 @@ Then render it from Erb.
 
 Much better!
 
+## 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.
+
+```ruby
+# Everything below is intentionally verbose!
+class SignupForm < ApplicationForm
+  def template
+    # The most basic type of input, which will be autofocused.
+    render 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)
+
+    # You can put fields in a block if that's your thing.
+    render field(:reason) do |f|
+      div do
+        f.label { "Why should we care about you?" }
+        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(
+        [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>
+      )
+    end
+
+    div do
+      render field(:source).label { "How did you hear about us?" }
+      render field(:source).select do |s|
+        # 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)
+          end
+        end
+      end
+    end
+
+    div do
+      render field(:agreement).label { "Check this box if you agree to give us your first born child" }
+      render field(:agreement).input(type: :checkbox, value: true)
+    end
+
+    render button { "Submit" }
+  end
+end
+```
+
 ## Extending Superforms
 
 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:
@@ -140,11 +199,11 @@ 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 everythign 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/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!
 
 ## Automatic strong parameters
 
-Guess what? Superform eliminates then 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.
+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.
 
 ```ruby
 class PostsController < ApplicationController

data/lib/superform/rails.rb

@@ -1,6 +1,19 @@
 module Superform
   module Rails
-    class Form < Phlex::HTML
+    # The `ApplicationComponent` is the superclass for all components in your application.
+    Component = ::ApplicationComponent
+
+    # A Phlex::HTML view module that accepts a model and sets a `Superform::Namespace`
+    # with the `Object#model_name` as the key and maps the object to form fields
+    # and namespaces.
+    #
+    # The `Form::Field` is a class that's meant to be extended so you can customize the `Form` inputs
+    # to your applications needs. Defaults for the `input`, `button`, `label`, and `textarea` tags
+    # are provided.
+    #
+    # The `Form` component also handles Rails authenticity tokens via the `authenticity_toklen_field`
+    # method and the HTTP verb via the `_method_field`.
+    class Form < Component
       attr_reader :model
 
       delegate \
@@ -12,6 +25,26 @@ module Superform
           :serialize,
         to: :@namespace
 
+      # The Field class is designed to be extended to create custom forms. To override,
+      # in your subclass you may have something like this:
+      #
+      # ```ruby
+      # class MyForm
+      #   class MyLabel < LabelComponent
+      #     def template(&content)
+      #       label(form: @field.dom.name, class: "text-bold", &content)
+      #     end
+      #   end
+      #
+      #   class Field < Field
+      #     def label(**attributes)
+      #       MyLabel.new(self, attributes: **attributes)
+      #     end
+      #   end
+      # end
+      # ```
+      #
+      # Now all calls to `label` will have the `text-bold` class applied to it.
       class Field < Superform::Field
         def button(**attributes)
           Components::ButtonComponent.new(self, attributes: attributes)
@@ -29,6 +62,10 @@ module Superform
           Components::TextareaComponent.new(self, attributes: attributes)
         end
 
+        def select(*collection, **attributes, &)
+          Components::SelectField.new(self, attributes: attributes, collection: collection, &)
+        end
+
         def title
           key.to_s.titleize
         end
@@ -42,19 +79,23 @@ module Superform
       end
 
       def around_template(&)
-        form action: form_action, method: form_method do
+        form_tag do
           authenticity_token_field
           _method_field
           super
         end
       end
 
+      def form_tag(&)
+        form action: form_action, method: form_method, &
+      end
+
       def template(&block)
         yield_content(&block)
       end
 
-      def submit(value = submit_value)
-        input(
+      def submit(value = submit_value, **attributes)
+        input **attributes.merge(
           name: "commit",
           type: "submit",
           value: value
@@ -62,42 +103,41 @@ module Superform
       end
 
       protected
+        def authenticity_token_field
+          input(
+            name: "authenticity_token",
+            type: "hidden",
+            value: helpers.form_authenticity_token
+          )
+        end
 
-      def authenticity_token_field
-        input(
-          name: "authenticity_token",
-          type: "hidden",
-          value: helpers.form_authenticity_token
-        )
-      end
-
-      def _method_field
-        input(
-          name: "_method",
-          type: "hidden",
-          value: _method_field_value
-        )
-      end
+        def _method_field
+          input(
+            name: "_method",
+            type: "hidden",
+            value: _method_field_value
+          )
+        end
 
-      def _method_field_value
-        @method || @model.persisted? ? "patch" : "post"
-      end
+        def _method_field_value
+          @method || @model.persisted? ? "patch" : "post"
+        end
 
-      def submit_value
-        "#{resource_action.to_s.capitalize} #{@model.model_name}"
-      end
+        def submit_value
+          "#{resource_action.to_s.capitalize} #{@model.model_name}"
+        end
 
-      def resource_action
-        @model.persisted? ? :update : :create
-      end
+        def resource_action
+          @model.persisted? ? :update : :create
+        end
 
-      def form_action
-        @action ||= helpers.url_for(action: resource_action)
-      end
+        def form_action
+          @action ||= helpers.url_for(action: resource_action)
+        end
 
-      def form_method
-        @method.to_s.downcase == "get" ? "get" : "post"
-      end
+        def form_method
+          @method.to_s.downcase == "get" ? "get" : "post"
+        end
     end
 
     module StrongParameters
@@ -112,8 +152,41 @@ module Superform
         end
     end
 
+    # Accept a collection of objects and map them to options suitable for form controls, like `select > options`
+    class OptionMapper
+      include Enumerable
+
+      def initialize(collection)
+        @collection = collection
+      end
+
+      def each(&options)
+        @collection.each do |object|
+          case object
+            in ActiveRecord::Relation => relation
+              active_record_relation_options_enumerable(relation).each(&options)
+            in id, value
+              options.call id, value
+            in value
+              options.call value, value.to_s
+          end
+        end
+      end
+
+      def active_record_relation_options_enumerable(relation)
+        Enumerator.new do |collection|
+          relation.each do |object|
+            attributes = object.attributes
+            id = attributes.delete(relation.primary_key)
+            value = attributes.values.join(" ")
+            collection << [ id, value ]
+          end
+        end
+      end
+    end
+
     module Components
-      class FieldComponent < ApplicationComponent
+      class BaseComponent < Component
         attr_reader :field, :dom
 
         delegate :dom, to: :field
@@ -139,9 +212,16 @@ module Superform
         end
       end
 
-      class LabelComponent < FieldComponent
-        def template(&)
-          label(**attributes) { field.key.to_s.titleize }
+      class FieldComponent < BaseComponent
+        def field_attributes
+          { id: dom.id, name: dom.name }
+        end
+      end
+
+      class LabelComponent < BaseComponent
+        def template(&content)
+          content ||= Proc.new { field.key.to_s.titleize }
+          label(**attributes, &content)
         end
 
         def field_attributes
@@ -150,8 +230,9 @@ module Superform
       end
 
       class ButtonComponent < FieldComponent
-        def template(&block)
-          button(**attributes) { button_text }
+        def template(&content)
+          content ||= Proc.new { button_text }
+          button(**attributes, &content)
         end
 
         def button_text
@@ -189,13 +270,48 @@ module Superform
       end
 
       class TextareaComponent < FieldComponent
-        def template(&)
-          textarea(**attributes) { dom.value }
+        def template(&content)
+          content ||= Proc.new { dom.value }
+          textarea(**attributes, &content)
         end
+      end
 
-        def field_attributes
-          { id: dom.id, name: dom.name }
+      class SelectField < FieldComponent
+        def initialize(*, collection: [], **, &)
+          super(*, **, &)
+          @collection = collection
         end
+
+        def template(&options)
+          if block_given?
+            select(**attributes, &options)
+          else
+            select(**attributes) { options(*@collection) }
+          end
+        end
+
+        def options(*collection)
+          map_options(collection).each do |key, value|
+            option(selected: field.value == key, value: key) { value }
+          end
+        end
+
+        def blank_option(&)
+          option(selected: field.value.nil?, &)
+        end
+
+        def true_option(&)
+          option(selected: field.value == true, value: true.to_s, &)
+        end
+
+        def false_option(&)
+          option(selected: field.value == false, value: false.to_s, &)
+        end
+
+        protected
+          def map_options(collection)
+            OptionMapper.new(collection)
+          end
       end
     end
   end

data/lib/superform/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Superform
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

data/lib/superform.rb

@@ -1,26 +1,44 @@
+require "zeitwerk"
+
 module Superform
-  class Error < StandardError; end
+  Loader = Zeitwerk::Loader.for_gem.tap do |loader|
+    loader.ignore "#{__dir__}/generators"
+    loader.setup
+  end
 
-  autoload :Rails, "superform/rails"
+  class Error < StandardError; end
 
+  # Generates DOM IDs, names, etc. for a Field, Namespace, or Node based on
+  # norms that were established by Rails. These can be used outsidef or Rails in
+  # other Ruby web frameworks since it has now dependencies on Rails.
   class DOM
     def initialize(field:)
       @field = field
     end
 
+    # Converts the value of the field to a String, which is required to work
+    # with Phlex. Assumes that `Object#to_s` emits a format suitable for the web form.
     def value
       @field.value.to_s
     end
 
+    # Walks from the current node to the parent node, grabs the names, and seperates
+    # them with a `_` for a DOM ID. One limitation of this approach is if multiple forms
+    # exist on the same page, the ID may be duplicate.
     def id
       lineage.map(&:key).join("_")
     end
 
+    # The `name` attribute of a node, which is influenced by Rails (not sure where Rails got
+    # it from). All node names, except the parent node, are wrapped in a `[]` and collections
+    # are left empty. For example, `user[addresses][][street]` would be created for a form with
+    # data shaped like `{user: {addresses: [{street: "Sesame Street"}]}}`.
     def name
       root, *names = keys
       names.map { |name| "[#{name}]" }.unshift(root).join
     end
 
+    # Emit the id, name, and value in an HTML tag-ish that doesnt have an element.
     def inspect
       "<id=#{id.inspect} name=#{name.inspect} value=#{value.inspect}/>"
     end
@@ -34,11 +52,15 @@ module Superform
       end
     end
 
+    # One-liner way of walking from the current node all the way up to the parent.
     def lineage
       Enumerator.produce(@field, &:parent).take_while(&:itself).reverse
     end
   end
 
+
+  # Superclass for Namespace and Field classes. Not much to it other than it has a `name`
+  # and `parent` node attribute. Think of it as a tree.
   class Node
     attr_reader :key, :parent
 
@@ -48,6 +70,13 @@ module Superform
     end
   end
 
+  # A Namespace maps and object to values, but doesn't actually have a value itself. For
+  # example, a `User` object or ActiveRecord model could be passed into the `:user` namespace.
+  # To access the values on a Namespace, the `field` can be called for single values.
+  #
+  # Additionally, to access namespaces within a namespace, such as if a `User has_many :addresses` in
+  # ActiveRecord, the `namespace` method can be called which will return another Namespace object and
+  # set the current Namespace as the parent.
   class Namespace < Node
     include Enumerable
 
@@ -61,28 +90,76 @@ module Superform
       yield self if block_given?
     end
 
+    # Creates a `Namespace` child instance with the parent set to the current instance, adds to
+    # the `@children` Hash to ensure duplicate child namespaces aren't created, then calls the
+    # method on the `@object` to get the child object to pass into that namespace.
+    #
+    # For example, if a `User#permission` returns a `Permission` object, we could map that to a
+    # form like this:
+    #
+    # ```ruby
+    # Superform :user, object: User.new do |form|
+    #   form.namespace :permission do |permission|
+    #     form.field :role
+    #   end
+    # end
+    # ```
     def namespace(key, &block)
       create_child(key, self.class, object: object_for(key: key), &block)
     end
 
+    # Maps the `Object#proprety` and `Object#property=` to a field in a web form that can be
+    # read and set by the form. For example, a User form might look like this:
+    #
+    # ```ruby
+    # Superform :user, object: User.new do |form|
+    #   form.field :email
+    #   form.field :name
+    # end
+    # ```
     def field(key)
-      create_child(key, @field_class, object: object)
-    end
-
-    def collection(key, &block)
-      create_child(key, NamespaceCollection, &block)
+      create_child(key, @field_class, object: object).tap do |field|
+        yield field if block_given?
+      end
     end
 
+    # Wraps an array of objects in Namespace classes. For example, if `User#addresses` returns
+    # an enumerable or array of `Address` classes:
+    #
+    # ```ruby
+    # Superform :user, object: User.new do |form|
+    #   form.field :email
+    #   form.field :name
+    #   form.collection :addresses do |address|
+    #     address.field(:street)
+    #     address.field(:state)
+    #     address.field(:zip)
+    #   end
+    # end
+    # ```
+    # The object within the block is a `Namespace` object that maps each object within the enumerable
+    # to another `Namespace` or `Field`.
+    def collection(key, &)
+      create_child(key, NamespaceCollection, &)
+    end
+
+    # Creates a Hash of Hashes and Arrays that represent the fields and collections of the Superform.
+    # This can be used to safely update ActiveRecord objects without the need for Strong Parameters.
+    # You will want to make sure that all the fields displayed in the form are ones that you're OK updating
+    # from the generated hash.
     def serialize
       each_with_object Hash.new do |child, hash|
         hash[child.key] = child.serialize
       end
     end
 
+    # Iterates through the children of the current namespace, which could be `Namespace` or `Field`
+    # objects.
     def each(&)
       @children.values.each(&)
     end
 
+    # Assigns a hash to the current namespace and children namespace.
     def assign(hash)
       each do |child|
         child.assign hash[child.key]
@@ -90,22 +167,30 @@ module Superform
       self
     end
 
-    def self.root(*args, **kwargs, &block)
-      new(*args, parent: nil, **kwargs, &block)
-    end
-    private
-
-    def create_child(key, child_class, **options, &block)
-      fetch(key) { child_class.new(key, parent: self, **options, &block) }
+    # Creates a root Namespace, which is essentially a form.
+    def self.root(*, **, &)
+      new(*, parent: nil, **, &)
     end
 
-    def fetch(key, &build)
-      @children[key] ||= build.call
-    end
+    protected
 
+    # Calls the corresponding method on the object for the `key` name, if it exists. For example
+    # if the `key` is `email` on `User`, this method would call `User#email` if the method is
+    # present.
+    #
+    # This method could be overwritten if the mapping between the `@object` and `key` name is not
+    # a method call. For example, a `Hash` would be accessed via `user[:email]` instead of `user.send(:email)`
     def object_for(key:)
       @object.send(key) if @object.respond_to? key
     end
+
+    private
+
+    # Checks if the child exists. If it does then it returns that. If it doesn't, it will
+    # build the child.
+    def create_child(key, child_class, **, &)
+      @children.fetch(key) { @children[key] = child_class.new(key, parent: self, **, &) }
+    end
   end
 
   class Field < Node
@@ -168,8 +253,8 @@ module Superform
 
     private
 
-    def build_field(**kwargs)
-      @field.class.new(@index += 1, parent: @field, **kwargs)
+    def build_field(**)
+      @field.class.new(@index += 1, parent: @field, **)
     end
   end
 
@@ -208,8 +293,8 @@ module Superform
       end
     end
 
-    def build_namespace(index, **kwargs)
-      parent.class.new(index, parent: self, **kwargs, &@template)
+    def build_namespace(index, **)
+      parent.class.new(index, parent: self, **, &@template)
     end
 
     def parent_collection

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: superform
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Brad Gessler
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-22 00:00:00.000000000 Z
+date: 2023-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex-rails
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
 description: A better way to customize and build forms for your Rails application
 email:
 - bradgessler@gmail.com