superform 0.5.1 → 0.6.1

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,108 @@ module Superform
     def collection(&)
       @collection ||= FieldCollection.new(field: self, &)
     end
+
+    # Make the name more obvious for extending or writing docs.
+    def field
+      self
+    end
+
+    # A helper, borrowed from Phlex, that makes it easy to "grab" values
+    # passed into a method that are reserved keywords. For example, this
+    # would throw a syntax error because `class` and `end` are reserved:
+    #
+    # def foo(end:, class:)
+    #   puts class
+    #   puts end
+    # end
+    #
+    # So you "grab" them like this:
+    # def foo(end:, class:)
+    #   puts grab(end:)
+    #   puts grab(class:)
+    # end
+    private def grab(**bindings)
+      if bindings.size > 1
+       	bindings.values
+      else
+     	  bindings.values.first
+      end
+    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/field.rb

@@ -0,0 +1,137 @@
+module Superform
+  module Rails
+    # 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(**, &)
+    #       MyLabel.new(self, **, &)
+    #     end
+    #
+    #     def input(class: nil, **)
+    #       super(class: ["input input-outline", grab(class:)])
+    #     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(field, attributes:)
+      end
+
+      def input(**attributes)
+        Components::Input.new(field, attributes:)
+      end
+
+      def checkbox(**attributes)
+        Components::Checkbox.new(field, attributes:)
+      end
+
+      def label(**attributes, &)
+        Components::Label.new(field, attributes:, &)
+      end
+
+      def textarea(**attributes)
+        Components::Textarea.new(field, attributes:)
+      end
+
+      def select(*collection, **attributes, &)
+        Components::Select.new(field, 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 text(*, **, &)
+        input(*, **, type: :text, &)
+      end
+
+      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
+  end
+end