superform 0.5.0 → 0.6.0

data/lib/superform/dom.rb

@@ -0,0 +1,51 @@
+module Superform
+  # 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
+
+    private
+
+    def keys
+      lineage.map do |node|
+        # If the parent of a field is a field, the name should be nil.
+        node.key unless node.parent.is_a? Field
+      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
+end

data/lib/superform/field.rb

@@ -0,0 +1,121 @@
+module Superform
+  # A Field represents the data associated with a form element. This class provides
+  # methods for accessing and modifying the field's value. HTML concerns are all
+  # delegated to the DOM object.
+  class Field < Node
+    attr_reader :dom
+
+    def initialize(key, parent:, object: nil, value: nil)
+      super key, parent: parent
+      @object = object
+      @value = value
+      @dom = Superform::DOM.new(field: self)
+      yield self if block_given?
+    end
+
+    def value
+      if @object and @object.respond_to? @key
+        @object.send @key
+      else
+        @value
+      end
+    end
+    alias :serialize :value
+
+    def assign(value)
+      if @object and @object.respond_to? "#{@key}="
+        @object.send "#{@key}=", value
+      else
+        @value = value
+      end
+    end
+    alias :value= :assign
+
+    # Wraps a field that's an array of values with a bunch of fields
+    # that are indexed with the array's index.
+    def collection(&)
+      @collection ||= FieldCollection.new(field: self, &)
+    end
+
+    # Make the name more obvious for extending or writing docs.
+    def field
+      self
+    end
+
+    # High-performance Kit proxy that wraps field methods with form.render calls.
+    # Uses Ruby class hooks to define methods at the class level for maximum speed:
+    # - Methods are defined once per Field class, not per Kit instance
+    # - True Ruby methods with full VM optimization (no method_missing overhead)
+    # - ~125x faster Kit instantiation compared to instance-level dynamic methods
+    # - Each Field subclass gets its own isolated Kit class with true isolation:
+    #   * Methods are copied at subclass creation time, not inherited dynamically
+    #   * Adding methods to a parent Field class won't affect existing subclass Kits
+    #   * Perfect for library design where you don't want parent changes affecting subclasses
+    class Kit
+      def initialize(field:, form:)
+        @field = field
+        @form = form
+      end
+    end
+
+    def self.inherited(subclass)
+      super
+      # Create a new Kit class for each Field subclass with true isolation
+      # Copy methods from parent Field classes at creation time, not through inheritance
+      subclass.const_set(:Kit, Class.new(Field::Kit))
+      
+      # Copy all existing methods from the inheritance chain
+      field_class = self
+      while field_class != Field
+        copy_field_methods_to_kit(field_class, subclass::Kit)
+        field_class = field_class.superclass
+      end
+    end
+
+    def self.method_added(method_name)
+      super
+      # Skip if this is the base Field class or if we don't have a Kit class yet
+      return if self == Field
+      return unless const_defined?(:Kit, false)
+      
+      # Only add method to THIS class's Kit, not subclasses (isolation)
+      add_method_to_kit(method_name, self::Kit)
+    end
+
+    def kit(form)
+      self.class::Kit.new(field: self, form: form)
+    end
+
+    private
+
+    def self.copy_field_methods_to_kit(field_class, kit_class)
+      base_methods = (Object.instance_methods + Node.instance_methods + 
+                     [:dom, :value, :serialize, :assign, :collection, :field, :kit]).to_set
+      
+      field_class.instance_methods(false).each do |method_name|
+        next if method_name.to_s.end_with?('=')
+        next if base_methods.include?(method_name)
+        next if kit_class.method_defined?(method_name)
+        
+        kit_class.define_method(method_name) do |*args, **kwargs, &block|
+          result = @field.send(method_name, *args, **kwargs, &block)
+          @form.render result
+        end
+      end
+    end
+
+    def self.add_method_to_kit(method_name, kit_class)
+      return if method_name.to_s.end_with?('=')
+      
+      base_methods = (Object.instance_methods + Node.instance_methods + 
+                     [:dom, :value, :serialize, :assign, :collection, :field, :kit]).to_set
+      return if base_methods.include?(method_name)
+      return if kit_class.method_defined?(method_name)
+      
+      kit_class.define_method(method_name) do |*args, **kwargs, &block|
+        result = @field.send(method_name, *args, **kwargs, &block)
+        @form.render result
+      end
+    end
+  end
+end

data/lib/superform/field_collection.rb

@@ -0,0 +1,33 @@
+module Superform
+  # A FieldCollection represents values that are collections of literals. For example, a Note
+  # ActiveRecord object might have a collection of tags that's an array of string literals.
+  class FieldCollection
+    include Enumerable
+
+    def initialize(field:, &)
+      @field = field
+      @index = 0
+      each(&) if block_given?
+    end
+
+    def each(&)
+      values.each do |value|
+        yield build_field(value: value)
+      end
+    end
+
+    def field
+      build_field
+    end
+
+    def values
+      Array(@field.value)
+    end
+
+    private
+
+    def build_field(**)
+      @field.class.new(@index += 1, parent: @field, **)
+    end
+  end
+end

data/lib/superform/form.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "phlex"
+
+module Superform
+  # A basic form component that inherits from Phlex::HTML and wraps content in a form tag.
+  # This provides a simple foundation for building forms without Rails dependencies.
+  #
+  # Example usage:
+  #   class MyForm < Superform::Form
+  #     def view_template
+  #       div { "Form content goes here" }
+  #     end
+  #   end
+  #
+  #   form = MyForm.new(action: "/users", method: :post)
+  #   form.call # renders <form action="/users" method="post">...</form>
+  class Form < Phlex::HTML
+    def initialize(action: nil, method: :post, **attributes)
+      @action = action
+      @method = method
+      @attributes = attributes
+      super()
+    end
+
+    def around_template(&block)
+      form(action: @action, method: @method, **@attributes, &block)
+    end
+
+    def build_field(key, parent:, object: nil, &block)
+      Field.new(key, parent: parent, object: object, &block)
+    end
+  end
+end

data/lib/superform/namespace.rb

@@ -0,0 +1,134 @@
+module Superform
+  # 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
+
+    attr_reader :object, :form
+
+    def initialize(key, parent:, object: nil, form: Superform::Form.new)
+      super(key, parent:)
+      @object = object
+      @form = form
+      @children = Hash.new
+      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, &)
+      @children[key] ||= build_namespace(key, &)
+    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, &)
+      @children[key] ||= build_field(key, &)
+    end
+
+    def Field(...)
+      field(...).kit(@form)
+    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, &)
+      @children[key] ||= build_collection(key, &)
+    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]
+      end
+      self
+    end
+
+    # Creates a root Namespace, which is essentially a form.
+    def self.root(*, **, &)
+      new(*, parent: nil, **, &)
+    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
+
+    # Builds a new field child
+    def build_field(key, &)
+      @form.build_field(key, parent: self, object:, &)
+    end
+
+    # Builds a new namespace child
+    def build_namespace(key, &)
+      self.class.new(key, parent: self, object: object_for(key:), form:, &)
+    end
+
+    # Builds a new collection child
+    def build_collection(key, &)
+      NamespaceCollection.new(key, parent: self, form:, &)
+    end
+  end
+end

data/lib/superform/namespace_collection.rb

@@ -0,0 +1,51 @@
+module Superform
+  # A NamespaceCollection represents values that are collections of namespaces. For example, a User
+  # ActiveRecord object might have many Addresses. Each individual address is then delegated out
+  # to a Namespace object.
+  class NamespaceCollection < Node
+    include Enumerable
+
+    attr_reader :form
+
+    def initialize(key, parent:, form: parent.form, &template)
+      super(key, parent:)
+      @template = template
+      @form = form
+      @namespaces = enumerate(parent_collection)
+    end
+
+    def serialize
+      map(&:serialize)
+    end
+
+    def assign(array)
+      # The problem with zip-ing the array is if I need to add new
+      # elements to it and wrap it in the namespace.
+      zip(array) do |namespace, hash|
+        namespace.assign hash
+      end
+    end
+
+    def each(&)
+      @namespaces.each(&)
+    end
+
+    private
+
+    def enumerate(enumerator)
+      Enumerator.new do |y|
+        enumerator.each.with_index do |object, key|
+          y << build_namespace(key, object:)
+        end
+      end
+    end
+
+    def build_namespace(index, **)
+      parent.class.new(index, parent: self, form:, **, &@template)
+    end
+
+    def parent_collection
+      @parent.object.send @key
+    end
+  end
+end

data/lib/superform/node.rb

@@ -0,0 +1,12 @@
+module Superform
+  # 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
+
+    def initialize(key, parent:)
+      @key = key
+      @parent = parent
+    end
+  end
+end

data/lib/superform/rails/components/base.rb

@@ -0,0 +1,31 @@
+module Superform
+  module Rails
+    module Components
+      class Base < Component
+        attr_reader :field, :dom
+
+        delegate :dom, to: :field
+
+        def initialize(field, attributes: {})
+          @field = field
+          @attributes = attributes
+        end
+
+        def field_attributes
+          {}
+        end
+
+        def focus(value = true)
+          @attributes[:autofocus] = value
+          self
+        end
+
+        private
+
+        def attributes
+          field_attributes.merge(@attributes)
+        end
+      end
+    end
+  end
+end

data/lib/superform/rails/components/button.rb

@@ -0,0 +1,20 @@
+module Superform
+  module Rails
+    module Components
+      class Button < Field
+        def view_template(&content)
+          content ||= Proc.new { button_text }
+          button(**attributes, &content)
+        end
+
+        def button_text
+          @attributes.fetch(:value, dom.value).titleize
+        end
+
+        def field_attributes
+          { id: dom.id, name: dom.name, value: dom.value }
+        end
+      end
+    end
+  end
+end

data/lib/superform/rails/components/checkbox.rb

@@ -0,0 +1,19 @@
+module Superform
+  module Rails
+    module Components
+      class Checkbox < Field
+        def view_template(&)
+          # Rails has a hidden and checkbox input to deal with sending back a value
+          # to the server regardless of if the input is checked or not.
+          input(name: dom.name, type: :hidden, value: "0")
+          # The hard coded keys need to be in here so the user can't overrite them.
+          input(type: :checkbox, value: "1", **attributes)
+        end
+
+        def field_attributes
+          { id: dom.id, name: dom.name, checked: field.value }
+        end
+      end
+    end
+  end
+end

data/lib/superform/rails/components/field.rb

@@ -0,0 +1,11 @@
+module Superform
+  module Rails
+    module Components
+      class Field < Base
+        def field_attributes
+          { id: dom.id, name: dom.name }
+        end
+      end
+    end
+  end
+end

data/lib/superform/rails/components/input.rb

@@ -0,0 +1,59 @@
+module Superform
+  module Rails
+    module Components
+      class Input < Field
+        def view_template(&)
+          input(**attributes)
+        end
+
+        def field_attributes
+          {
+            id: dom.id,
+            name: dom.name,
+            type: type,
+            value: value
+          }
+        end
+
+        def has_client_provided_value?
+          case type.to_s
+          when "file", "image"
+            true
+          else
+            false
+          end
+        end
+
+        def value
+          dom.value unless has_client_provided_value?
+        end
+
+        def type
+          @type ||= ActiveSupport::StringInquirer.new(attribute_type || value_type)
+        end
+
+        protected
+          def value_type
+            case field.value
+            when URI
+              "url"
+            when Integer, Float
+              "number"
+            when Date, DateTime
+              "date"
+            when Time
+              "time"
+            else
+              "text"
+            end
+          end
+
+          def attribute_type
+            if type = @attributes[:type] || @attributes["type"]
+              type.to_s
+            end
+          end
+      end
+    end
+  end
+end

data/lib/superform/rails/components/label.rb

@@ -0,0 +1,20 @@
+module Superform
+  module Rails
+    module Components
+      class Label < Base
+        def view_template(&content)
+          content ||= Proc.new { label_text }
+          label(**attributes, &content)
+        end
+
+        def field_attributes
+          { for: dom.id }
+        end
+
+        def label_text
+          field.key.to_s.titleize
+        end
+      end
+    end
+  end
+end

data/lib/superform/rails/components/select.rb

@@ -0,0 +1,43 @@
+module Superform
+  module Rails
+    module Components
+      class Select < Field
+        def initialize(*, collection: [], **, &)
+          super(*, **, &)
+          @collection = collection
+        end
+
+        def view_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
+end

data/lib/superform/rails/components/textarea.rb

@@ -0,0 +1,12 @@
+module Superform
+  module Rails
+    module Components
+      class Textarea < Field
+        def view_template(&content)
+          content ||= Proc.new { dom.value }
+          textarea(**attributes, &content)
+        end
+      end
+    end
+  end
+end