superform 0.5.1 → 0.6.0

data/lib/superform/field.rb

@@ -10,6 +10,7 @@ module Superform
       @object = object
       @value = value
       @dom = Superform::DOM.new(field: self)
+      yield self if block_given?
     end
 
     def value
@@ -35,5 +36,86 @@ module Superform
     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/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

@@ -9,12 +9,12 @@ module Superform
   class Namespace < Node
     include Enumerable
 
-    attr_reader :object
+    attr_reader :object, :form
 
-    def initialize(key, parent:, object: nil, field_class: Field)
-      super(key, parent: parent)
+    def initialize(key, parent:, object: nil, form: Superform::Form.new)
+      super(key, parent:)
       @object = object
-      @field_class = field_class
+      @form = form
       @children = Hash.new
       yield self if block_given?
     end
@@ -33,8 +33,8 @@ module Superform
     #   end
     # end
     # ```
-    def namespace(key, &block)
-      create_child(key, self.class, object: object_for(key: key), &block)
+    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
@@ -46,12 +46,13 @@ module Superform
     #   form.field :name
     # end
     # ```
-    def field(key)
-      create_child(key, @field_class, object: object).tap do |field|
-        yield field if block_given?
-      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:
     #
@@ -69,7 +70,7 @@ module Superform
     # 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, &)
+      @children[key] ||= build_collection(key, &)
     end
 
     # Creates a Hash of Hashes and Arrays that represent the fields and collections of the Superform.
@@ -115,10 +116,19 @@ module Superform
 
     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, **kwargs, &block)
-      @children.fetch(key) { @children[key] = child_class.new(key, parent: self, **kwargs, &block) }
+    # 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

@@ -5,9 +5,12 @@ module Superform
   class NamespaceCollection < Node
     include Enumerable
 
-    def initialize(key, parent:, &template)
-      super(key, parent: parent)
+    attr_reader :form
+
+    def initialize(key, parent:, form: parent.form, &template)
+      super(key, parent:)
       @template = template
+      @form = form
       @namespaces = enumerate(parent_collection)
     end
 
@@ -32,13 +35,13 @@ module Superform
     def enumerate(enumerator)
       Enumerator.new do |y|
         enumerator.each.with_index do |object, key|
-          y << build_namespace(key, object: object)
+          y << build_namespace(key, object:)
         end
       end
     end
 
     def build_namespace(index, **)
-      parent.class.new(index, parent: self, **, &@template)
+      parent.class.new(index, parent: self, form:, **, &@template)
     end
 
     def parent_collection

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

data/lib/superform/rails/form.rb

@@ -0,0 +1,240 @@
+module Superform
+  module Rails
+    # 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
+      include Phlex::Rails::Helpers::FormAuthenticityToken
+      include Phlex::Rails::Helpers::URLFor
+
+      attr_accessor :model
+
+      delegate \
+          :Field,
+          :field,
+          :collection,
+          :namespace,
+          :assign,
+          :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 < Superform::Rails::Form
+      #   class MyLabel < Superform::Rails::Components::Label
+      #     def view_template(&content)
+      #       label(form: @field.dom.name, class: "text-bold", &content)
+      #     end
+      #   end
+      #
+      #   class Field < Field
+      #     def label(**attributes)
+      #       MyLabel.new(self, **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::Button.new(self, attributes:)
+        end
+
+        def input(**attributes)
+          Components::Input.new(self, attributes:)
+        end
+
+        def text(*, **, &)
+          input(*, **, type: :text, &)
+        end
+
+        def checkbox(**attributes)
+          Components::Checkbox.new(self, attributes:)
+        end
+
+        def label(**attributes, &)
+          Components::Label.new(self, attributes:, &)
+        end
+
+        def textarea(**attributes)
+          Components::Textarea.new(self, attributes:)
+        end
+
+        def select(*collection, **attributes, &)
+          Components::Select.new(self, attributes:, collection:, &)
+        end
+
+        # HTML5 input type convenience methods - clean API without _field suffix
+        # Examples:
+        #   field(:email).email(class: "form-input")
+        #   field(:age).number(min: 18, max: 99)
+        #   field(:birthday).date
+        #   field(:secret).hidden(value: "token123")
+        #   field(:gender).radio("male", id: "user_gender_male")
+        def hidden(*, **, &)
+          input(*, **, type: :hidden, &)
+        end
+
+        def password(*, **, &)
+          input(*, **, type: :password, &)
+        end
+
+        def email(*, **, &)
+          input(*, **, type: :email, &)
+        end
+
+        def url(*, **, &)
+          input(*, **, type: :url, &)
+        end
+
+        def tel(*, **, &)
+          input(*, **, type: :tel, &)
+        end
+        alias_method :phone, :tel
+
+        def number(*, **, &)
+          input(*, **, type: :number, &)
+        end
+
+        def range(*, **, &)
+          input(*, **, type: :range, &)
+        end
+
+        def date(*, **, &)
+          input(*, **, type: :date, &)
+        end
+
+        def time(*, **, &)
+          input(*, **, type: :time, &)
+        end
+
+        def datetime(*, **, &)
+          input(*, **, type: :"datetime-local", &)
+        end
+
+        def month(*, **, &)
+          input(*, **, type: :month, &)
+        end
+
+        def week(*, **, &)
+          input(*, **, type: :week, &)
+        end
+
+        def color(*, **, &)
+          input(*, **, type: :color, &)
+        end
+
+        def search(*, **, &)
+          input(*, **, type: :search, &)
+        end
+
+        def file(*, **, &)
+          input(*, **, type: :file, &)
+        end
+
+        def radio(value, *, **, &)
+          input(*, **, type: :radio, value: value, &)
+        end
+
+        # Rails compatibility aliases
+        alias_method :check_box, :checkbox
+        alias_method :text_area, :textarea
+
+        def title
+          key.to_s.titleize
+        end
+      end
+
+      def build_field(...)
+        self.class::Field.new(...)
+      end
+
+      def initialize(model, action: nil, method: nil, **attributes)
+        @model = model
+        @action = action
+        @method = method
+        @attributes = attributes
+        @namespace = Namespace.root(key, object: model, form: self)
+      end
+
+      def around_template(&)
+        form_tag do
+          authenticity_token_field
+          _method_field
+          super
+        end
+      end
+
+      def form_tag(&)
+        form action: form_action, method: form_method, **@attributes, &
+      end
+
+      def view_template(&block)
+        yield self if block_given?
+      end
+
+      def submit(value = submit_value, **attributes)
+        input **attributes.merge(
+          name: "commit",
+          type: "submit",
+          value: value
+        )
+      end
+
+      def key
+        @model.model_name.param_key
+      end
+
+      protected
+        def authenticity_token_field
+          input(
+            name: "authenticity_token",
+            type: "hidden",
+            value: form_authenticity_token
+          )
+        end
+
+        def _method_field
+          input(
+            name: "_method",
+            type: "hidden",
+            value: _method_field_value
+          )
+        end
+
+        def _method_field_value
+          @method || resource_method_field_value
+        end
+
+        def resource_method_field_value
+          @model.persisted? ? "patch" : "post"
+        end
+
+        def submit_value
+          "#{resource_action.to_s.capitalize} #{@model.model_name}"
+        end
+
+        def resource_action
+          @model.persisted? ? :update : :create
+        end
+
+        def form_action
+          @action ||= url_for(action: resource_action)
+        end
+
+        def form_method
+          @method.to_s.downcase == "get" ? "get" : "post"
+        end
+    end
+  end
+end