phlexi-form 0.2.0 → 0.3.0

data/lib/phlexi/form/structure/field_builder.rb

@@ -5,13 +5,22 @@ require "phlex"
 module Phlexi
   module Form
     module Structure
+      # FieldBuilder class is responsible for building form fields with various options and components.
+      #
+      # @attr_reader [Structure::DOM] dom The DOM structure for the field.
+      # @attr_reader [Hash] options Options for the field.
+      # @attr_reader [Object] object The object associated with the field.
+      # @attr_reader [Hash] attributes Attributes for the field.
+      # @attr_accessor [Object] value The value of the field.
       class FieldBuilder < Node
         include Phlex::Helpers
+        include FieldOptions::Associations
+        include FieldOptions::Themes
         include FieldOptions::Validators
         include FieldOptions::Labels
         include FieldOptions::Hints
         include FieldOptions::Errors
-        include FieldOptions::Type
+        include FieldOptions::InferredTypes
         include FieldOptions::Collection
         include FieldOptions::Placeholder
         include FieldOptions::Required
@@ -24,175 +33,210 @@ module Phlexi
         include FieldOptions::Multiple
         include FieldOptions::Limit
 
-        attr_reader :dom, :options, :object, :attributes
-        attr_accessor :value
-        alias_method :serialize, :value
-        alias_method :assign, :value=
+        attr_reader :dom, :options, :object, :input_attributes, :value
 
-        def initialize(key, parent:, object: nil, value: :__i_form_builder_nil_value_i__, attributes: {}, **options)
-          key = :"#{key}"
+        # Initializes a new FieldBuilder instance.
+        #
+        # @param key [Symbol, String] The key for the field.
+        # @param parent [Structure::Namespace] The parent object.
+        # @param object [Object, nil] The associated object.
+        # @param value [Object] The initial value for the field.
+        # @param input_attributes [Hash] Default attributes to apply to input fields.
+        # @param options [Hash] Additional options for the field.
+        def initialize(key, parent:, object: nil, value: NIL_VALUE, input_attributes: {}, **options)
           super(key, parent: parent)
 
           @object = object
-          @value = if value != :__i_form_builder_nil_value_i__
-            value
-          else
-            object.respond_to?(key) ? object.send(key) : nil
-          end
-          @attributes = attributes
+          @value = determine_initial_value(value)
+          @input_attributes = input_attributes
           @options = options
           @dom = Structure::DOM.new(field: self)
         end
 
-        def label_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          label_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :label)
-          Components::Label.new(self, class: label_class, **attributes)
+        # Creates a label tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the label.
+        # @return [Components::Label] The label component.
+        def label_tag(**, &)
+          create_component(Components::Label, :label, **, &)
         end
 
-        def input_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          input_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :input)
-          Components::Input.new(self, class: input_class, **attributes)
+        # Creates an input tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the input.
+        # @return [Components::Input] The input component.
+        def input_tag(**, &)
+          create_component(Components::Input, :input, **, &)
         end
 
-        def checkbox_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          checkbox_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :checkbox)
-          Components::Checkbox.new(self, class: checkbox_class, **attributes)
+        def file_input_tag(**, &)
+          create_component(Components::FileInput, :file, **, &)
         end
 
-        def collection_checkboxes_tag(**attributes, &)
-          attributes = self.attributes.deep_merge(attributes)
-          collection_checkboxes_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :collection_checkboxes)
-          Components::CollectionCheckboxes.new(self, class: collection_checkboxes_class, **attributes, &)
+        # Creates a checkbox tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the checkbox.
+        # @return [Components::Checkbox] The checkbox component.
+        def checkbox_tag(**, &)
+          create_component(Components::Checkbox, :checkbox, **, &)
         end
 
-        def radio_button_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          radio_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :radio)
-          Components::RadioButton.new(self, class: radio_class, **attributes)
+        # Creates collection checkboxes for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the collection checkboxes.
+        # @yield [block] The block to be executed for each checkbox.
+        # @return [Components::CollectionCheckboxes] The collection checkboxes component.
+        def collection_checkboxes_tag(**, &)
+          create_component(Components::CollectionCheckboxes, :collection_checkboxes, **, &)
         end
 
-        def collection_radio_buttons_tag(**attributes, &)
-          attributes = self.attributes.deep_merge(attributes)
-          collection_radio_buttons_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :collection_radio_buttons)
-          Components::CollectionRadioButtons.new(self, class: collection_radio_buttons_class, **attributes, &)
+        # Creates a radio button tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the radio button.
+        # @return [Components::RadioButton] The radio button component.
+        def radio_button_tag(**, &)
+          create_component(Components::RadioButton, :radio, **, &)
         end
 
-        def textarea_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          textarea_class = attributes.delete(:class) || themed_input(attributes.delete(:theme) || :textarea)
-          Components::Textarea.new(self, class: textarea_class, **attributes)
+        # Creates collection radio buttons for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the collection radio buttons.
+        # @yield [block] The block to be executed for each radio button.
+        # @return [Components::CollectionRadioButtons] The collection radio buttons component.
+        def collection_radio_buttons_tag(**, &)
+          create_component(Components::CollectionRadioButtons, :collection_radio_buttons, **, &)
         end
 
-        def select_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          select_class = attributes.delete(:class) || themed_input(attributes.delete(:theme) || :select)
-          Components::Select.new(self, class: select_class, **attributes)
+        # Creates a textarea tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the textarea.
+        # @return [Components::Textarea] The textarea component.
+        def textarea_tag(**, &)
+          create_component(Components::Textarea, :textarea, **, &)
         end
 
-        def hint_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          hint_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :hint)
-          Components::Hint.new(self, class: hint_class, **attributes)
+        # Creates a select tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the select.
+        # @return [Components::Select] The select component.
+        def select_tag(**, &)
+          create_component(Components::Select, :select, **, &)
         end
 
-        def error_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          error_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :error)
-          Components::Error.new(self, class: error_class, **attributes)
+        def input_array_tag(**, &)
+          create_component(Components::InputArray, :array, **, &)
         end
 
-        def full_error_tag(**attributes)
-          attributes = self.attributes.deep_merge(attributes)
-          error_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :error)
-          Components::FullError.new(self, class: error_class, **attributes)
+        # Creates a hint tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the hint.
+        # @return [Components::Hint] The hint component.
+        def hint_tag(**, &)
+          create_component(Components::Hint, :hint, **, &)
         end
 
-        def wrapped(inner: {}, **attributes, &)
-          attributes = self.attributes.deep_merge(attributes)
-          wrapper_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :wrapper)
-          inner[:class] = inner.delete(:class) || themed(inner.delete(:theme) || :inner_wrapper)
-          Components::Wrapper.new(self, class: wrapper_class, inner:, **attributes, &)
+        # Creates an error tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the error.
+        # @return [Components::Error] The error component.
+        def error_tag(**, &)
+          create_component(Components::Error, :error, **, &)
         end
 
-        # Wraps a field that's an array of values with a bunch of fields
+        # Creates a full error tag for the field.
         #
-        # @example Usage
+        # @param attributes [Hash] Additional attributes for the full error.
+        # @return [Components::FullError] The full error component.
+        def full_error_tag(**, &)
+          create_component(Components::FullError, :full_error, **, &)
+        end
+
+        # Wraps the field with additional markup.
         #
-        # ```ruby
-        # Phlexi::Form.new User.new do
-        #   render field(:email).input_tag
-        #   render field(:name).input_tag
-        #   field(:roles).multi([["Admin", "admin"], ["Editor", "editor"]]) do |a|
-        #     render a.label_tag
-        #     render a.input_tag # => name="user[roles][]"
-        #   end
-        # end
-        # ```
-        # The object within the block is a `FieldCollection` object
-        def multi(range = nil, &)
-          range ||= Array(collection)
-          FieldCollection.new(field: self, range:, &)
+        # @param inner [Hash] Attributes for the inner wrapper.
+        # @param attributes [Hash] Additional attributes for the wrapper.
+        # @yield [block] The block to be executed within the wrapper.
+        # @return [Components::Wrapper] The wrapper component.
+        def wrapped(inner: {}, **attributes, &)
+          attributes = apply_component_theme(attributes, :wrapper)
+          inner = apply_component_theme(inner, :inner_wrapper)
+          Components::Wrapper.new(self, inner: inner, **attributes, &)
         end
 
-        private
+        # Creates a repeated field collection.
+        #
+        # @param range [Integer, #to_a] The range of keys for each field.
+        #   If an integer (e.g. 6) is passed, it is converted to a range = 1..6
+        # @yield [block] The block to be executed for each item in the collection.
+        # @return [FieldCollection] The field collection.
+        def repeated(range = nil, &)
+          FieldCollection.new(field: self, range: range, &)
+        end
 
-        def themed(component)
-          tokens(resolve_theme(component), resolve_validity_theme(component)).presence if component
+        # Creates a submit button
+        #
+        # @param attributes [Hash] Additional attributes for the submit.
+        # @return [Components::SubmitButton] The submit button component.
+        def submit_button_tag(**, &)
+          create_component(Components::SubmitButton, :submit_button, **, &)
         end
 
-        def themed_input(input_component)
-          themed(input_component) || themed(:input) if input_component
+        def extract_input(params)
+          raise "field##{dom.name} did not define an input component" unless @field_input_extractor
+
+          @field_input_extractor.extract_input(params)
         end
 
-        def resolve_theme(property)
-          options[property] || theme[property]
+        protected
+
+        def create_component(component_class, theme_key, **attributes, &)
+          attributes = mix(input_attributes, attributes) if component_class.include?(Phlexi::Form::Components::Concerns::HandlesInput)
+          component = component_class.new(self, **apply_component_theme(attributes, theme_key), &)
+          if component_class.include?(Components::Concerns::ExtractsInput)
+            raise "input component already defined: #{@field_input_extractor.inspect}" if @field_input_extractor
+
+            @field_input_extractor = component
+          end
+
+          component
         end
 
-        def resolve_validity_theme(property)
-          validity_property = if has_errors?
-            # Apply invalid class if the object has errors
-            :"invalid_#{property}"
-          elsif (object.respond_to?(:persisted?) && object.persisted?) && (object.respond_to?(:errors) && !object.errors.empty?)
-            # The object is persisted, has been validated, and there are errors (not empty), but this field has no errors
-            # Apply valid class
-            :"valid_#{property}"
+        def apply_component_theme(attributes, theme_key)
+          theme_key = attributes.delete(:theme) || theme_key
+          if attributes.key?(:class!)
+            attributes
           else
-            :"neutral_#{property}"
+            mix({class: themed(theme_key)}, attributes)
           end
-
-          resolve_theme(validity_property)
-        end
-
-        def theme
-          @theme ||= {
-            # # label themes
-            # label: "md:w-1/6 mt-2 block mb-2 text-sm font-medium",
-            # invalid_label: "text-red-700 dark:text-red-500",
-            # valid_label: "text-green-700 dark:text-green-500",
-            # neutral_label: "text-gray-700 dark:text-white",
-            # # input themes
-            # input: "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700",
-            # invalid_input: "bg-red-50 border-red-500 dark:border-red-500 text-red-900 dark:text-red-500 placeholder-red-700 dark:placeholder-red-500 focus:ring-red-500 focus:border-red-500",
-            # valid_input: "bg-green-50 border-green-500 dark:border-green-500 text-green-900 dark:text-green-400 placeholder-green-700 dark:placeholder-green-500 focus:ring-green-500 focus:border-green-500",
-            # neutral_input: "border-gray-300 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white focus:ring-primary-500 focus:border-primary-500",
-            # # hint themes
-            # hint: "mt-2 text-sm text-gray-500 dark:text-gray-200",
-            # # error themes
-            # error: "mt-2 text-sm text-red-600 dark:text-red-500",
-            # # wrapper themes
-            # wrapper: "flex flex-col md:flex-row items-start space-y-2 md:space-y-0 md:space-x-2 mb-4",
-            # inner_wrapper: "md:w-5/6 w-full",
-          }.freeze
-        end
-
-        def reflection = nil
+        end
 
         def has_value?
           value.present?
         end
+
+        def determine_initial_value(value)
+          return value unless value == NIL_VALUE
+
+          determine_value_from_association || determine_value_from_object
+        end
+
+        def determine_value_from_object
+          object.respond_to?(key) ? object.public_send(key) : nil
+        end
+
+        def determine_value_from_association
+          return nil unless association_reflection.present?
+
+          value = object.public_send(key)
+          case association_reflection.macro
+          when :has_many, :has_and_belongs_to_many
+            value&.map { |v| v.public_send(association_reflection.klass.primary_key) }
+          when :belongs_to, :has_one
+            value&.public_send(association_reflection.klass.primary_key)
+          else
+            raise ArgumentError, "Unsupported association type: #{association_reflection.macro}"
+          end
+        end
       end
     end
   end

data/lib/phlexi/form/structure/field_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "phlex"
+
 module Phlexi
   module Form
     module Structure
@@ -7,18 +9,30 @@ module Phlexi
         include Enumerable
 
         class Builder
-          attr_reader :key
+          include Phlex::Helpers
+
+          attr_reader :key, :index
 
-          def initialize(key, field)
+          def initialize(key, field, index)
             @key = key.to_s
             @field = field
+            @index = index
           end
 
-          def field(**)
-            @field.class.new(key, attributes: @field.attributes, **, parent: @field).tap do |field|
+          def field(**options)
+            options = mix({input_attributes: @field.input_attributes}, options)
+            @field.class.new(key, **options, parent: @field).tap do |field|
               yield field if block_given?
             end
           end
+
+          def hidden_field_tag(value: "", force: false)
+            raise "Attempting to build hidden field on non-first field in a collection" unless index == 0 || force
+
+            @field.class
+              .new("hidden", parent: @field)
+              .input_tag(type: :hidden, value:)
+          end
         end
 
         def initialize(field:, range:, &)
@@ -35,8 +49,8 @@ module Phlexi
         end
 
         def each(&)
-          @range.each do |key|
-            yield Builder.new(key, @field)
+          @range.each.with_index do |key, index|
+            yield Builder.new(key, @field, index)
           end
         end
       end

data/lib/phlexi/form/structure/namespace.rb

@@ -3,22 +3,27 @@
 module Phlexi
   module Form
     module Structure
-      # A Namespace maps and object to values, but doesn't actually have a value itself. For
+      # A Namespace maps an 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.
+      # To access single values on a Namespace, #field can be used.
+      #
+      # To access nested objects within a namespace, two methods are available:
+      #
+      # 1. #nest_one: Used for single nested objects, such as if a `User belongs_to :profile` in
+      #    ActiveRecord. This method returns another Namespace object.
+      #
+      # 2. #nest_many: Used for collections of nested objects, such as if a `User has_many :addresses` in
+      #    ActiveRecord. This method returns a NamespaceCollection object.
       class Namespace < Structure::Node
         include Enumerable
 
         attr_reader :builder_klass, :object
 
-        def initialize(key, parent:, object: nil, builder_klass: Field)
+        def initialize(key, parent:, builder_klass:, object: nil)
           super(key, parent: parent)
-          @object = object
           @builder_klass = builder_klass
+          @object = object
           @children = {}
           yield self if block_given?
         end
@@ -29,6 +34,10 @@ module Phlexi
           end
         end
 
+        def submit_button(key = :submit_button, **, &)
+          field(key).submit_button_tag(**, &)
+        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.
@@ -37,14 +46,14 @@ module Phlexi
         # form like this:
         #
         # ```ruby
-        # Superform :user, object: User.new do |form|
-        #   form.nest_one :permission do |permission|
-        #     form.field :role
+        # Phlexi::Form(User.new, as: :user) do
+        #   nest_one :profile do |profile|
+        #     render profile.field(:gender).input_tag
         #   end
         # end
         # ```
         def nest_one(key, object: nil, &)
-          object ||= object_for(key: key)
+          object ||= object_value_for(key: key)
           create_child(key, self.class, object:, builder_klass:, &)
         end
 
@@ -52,10 +61,10 @@ module Phlexi
         # an enumerable or array of `Address` classes:
         #
         # ```ruby
-        # Phlexi::Form.new User.new do |form|
-        #   render form.field(:email).input_tag
-        #   render form.field(:name).input_tag
-        #   form.nest_many :addresses do |address|
+        # Phlexi::Form(User.new) do
+        #   render field(:email).input_tag
+        #   render field(:name).input_tag
+        #   nest_many :addresses do |address|
         #     render address.field(:street).input_tag
         #     render address.field(:state).input_tag
         #     render address.field(:zip).input_tag
@@ -65,17 +74,20 @@ module Phlexi
         # The object within the block is a `Namespace` object that maps each object within the enumerable
         # to another `Namespace` or `Field`.
         def nest_many(key, collection: nil, &)
-          collection ||= Array(object_for(key: key))
+          collection ||= Array(object_value_for(key: key))
           create_child(key, NamespaceCollection, collection:, &)
         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({}) do |child, hash|
-            hash[child.key] = child.serialize
+        def extract_input(params)
+          if params.is_a?(Array)
+            each_with_object({}) do |child, hash|
+              hash.merge! child.extract_input(params[0])
+            end
+          else
+            input = each_with_object({}) do |child, hash|
+              hash.merge! child.extract_input(params[key])
+            end
+            {key => input}
           end
         end
 
@@ -85,17 +97,22 @@ module Phlexi
           @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]
+        def dom_id
+          @dom_id ||= begin
+            id = if object.nil?
+              nil
+            elsif object.class.respond_to?(:primary_key)
+              object.public_send(object.class.primary_key) || :new
+            elsif object.respond_to?(:id)
+              object.id || :new
+            end
+            [key, id].compact.join("_").underscore
           end
-          self
         end
 
         # Creates a root Namespace, which is essentially a form.
-        def self.root(*, **, &)
-          new(*, parent: nil, **, &)
+        def self.root(*, builder_klass:, **, &)
+          new(*, parent: nil, builder_klass:, **, &)
         end
 
         protected
@@ -106,7 +123,7 @@ module Phlexi
         #
         # 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:)
+        def object_value_for(key:)
           @object.send(key) if @object.respond_to? key
         end
 

data/lib/phlexi/form/structure/namespace_collection.rb

@@ -6,36 +6,36 @@ module Phlexi
       class NamespaceCollection < Node
         include Enumerable
 
-        def initialize(key, parent:, collection: nil, &)
+        def initialize(key, parent:, collection: nil, &block)
+          raise ArgumentError, "block is required" unless block.present?
+
           super(key, parent: parent)
 
-          @namespaces = enumerate(collection)
-          each(&) if block_given?
+          @collection = collection
+          @block = block
+          each(&block)
         end
 
-        def serialize
-          map(&:serialize)
-        end
+        def extract_input(params)
+          namespace = build_namespace(0)
+          @block.call(namespace)
 
-        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
+          inputs = params[key].map { |param| namespace.extract_input([param]) }
+          {key => inputs}
         end
 
+        private
+
         def each(&)
-          @namespaces.each(&)
+          namespaces.each(&)
         end
 
-        private
-
-        def enumerate(enumerator)
-          Enumerator.new do |y|
-            enumerator.each.with_index do |object, key|
-              y << build_namespace(key, object: object)
-            end
+        # Builds and memoizes namespaces for the collection.
+        #
+        # @return [Array<Namespace>] An array of namespace objects.
+        def namespaces
+          @namespaces ||= @collection.map.with_index do |object, key|
+            build_namespace(key, object: object)
           end
         end
 

data/lib/phlexi/form/structure/node.rb

@@ -3,15 +3,25 @@
 module Phlexi
   module Form
     module Structure
-      # 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.
+      # Superclass for Namespace and Field classes. Represents a node in the form tree structure.
+      #
+      # @attr_reader [Symbol] key The node's key
+      # @attr_reader [Node, nil] parent The node's parent in the tree structure
       class Node
         attr_reader :key, :parent
 
+        # Initializes a new Node instance.
+        #
+        # @param key [Symbol, String] The key for the node
+        # @param parent [Node, nil] The parent node
         def initialize(key, parent:)
-          @key = key
+          @key = :"#{key}"
           @parent = parent
         end
+
+        def inspect
+          "<#{self.class.name} key=#{key.inspect} parent=#{id.inspect} />"
+        end
       end
     end
   end

data/lib/phlexi/form/version.rb

@@ -2,6 +2,6 @@
 
 module Phlexi
   module Form
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end