phlexi-form 0.2.0 → 0.3.0.rc1

data/lib/phlexi/form/field_options/themes.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Form
+    module FieldOptions
+      module Themes
+        # Resolves theme classes for components based on their type and the validity state of the field.
+        #
+        # This method is responsible for determining the appropriate CSS classes for a given form component.
+        # It considers both the base theme for the component type and any additional theming based on the
+        # component's validity state (valid, invalid, or neutral). The method supports a hierarchical
+        # theming system, allowing for cascading themes and easy customization.
+        #
+        # @param component [Symbol, String] The type of form component (e.g., :input, :label, :wrapper)
+        #
+        # @return [String, nil] A string of CSS classes for the component, or nil if no theme is applied
+        #
+        # @example Basic usage
+        #   themed(:input)
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700"
+        #
+        # @example Usage with validity state
+        #   # Assuming the field has errors
+        #   themed(:input)
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700 bg-red-50 border-red-500 text-red-900"
+        #
+        # @example Cascading themes
+        #   # Assuming textarea inherits from input in the theme definition
+        #   themed(:textarea)
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700"
+        #
+        # @note The actual CSS classes returned will depend on the theme definitions in the `theme` hash
+        #       and any overrides specified in the `options` hash.
+        #
+        # @see #resolve_theme
+        # @see #resolve_validity_theme
+        # @see #theme
+        def themed(component)
+          return unless component
+
+          tokens(resolve_theme(component), resolve_validity_theme(component)).presence
+        end
+
+        protected
+
+        # Recursively resolves the theme for a given property, handling nested symbol references
+        #
+        # @param property [Symbol, String] The theme property to resolve
+        # @param visited [Set] Set of already visited properties to prevent infinite recursion
+        # @return [String, nil] The resolved theme value or nil if not found
+        #
+        # @example Resolving a nested theme
+        #   # Assuming the theme is: { input: :base_input, base_input: "some-class" }
+        #   resolve_theme(:input)
+        #   # => "some-class"
+        def resolve_theme(property, visited = Set.new)
+          return nil if !property.present? || visited.include?(property)
+          visited.add(property)
+
+          result = theme[property]
+          if result.is_a?(Symbol)
+            resolve_theme(result, visited)
+          else
+            result
+          end
+        end
+
+        # Resolves the theme for a component based on its current validity state
+        #
+        # This method determines the validity state of the field (valid, invalid, or neutral)
+        # and returns the corresponding theme by prepending the state to the component name.
+        #
+        # @param property [Symbol, String] The base theme property to resolve
+        # @return [String, nil] The resolved validity-specific theme or nil if not found
+        #
+        # @example Resolving a validity theme
+        #   # Assuming the field has errors and the theme includes { invalid_input: "error-class" }
+        #   resolve_validity_theme(:input)
+        #   # => "error-class"
+        def resolve_validity_theme(property)
+          validity_property = if has_errors?
+            :"invalid_#{property}"
+          elsif object_valid?
+            :"valid_#{property}"
+          else
+            :"neutral_#{property}"
+          end
+
+          resolve_theme(validity_property)
+        end
+
+        # Retrieves or initializes the theme hash for the form builder.
+        #
+        # This method returns a hash containing theme definitions for various form components.
+        # If a theme has been explicitly set in the options, it returns that. Otherwise, it
+        # initializes and returns a default theme.
+        #
+        # The theme hash defines CSS classes or references to other theme keys for different
+        # components and their states (e.g., valid, invalid, neutral).
+        #
+        # @return [Hash] A hash containing theme definitions for form components
+        #
+        # @example Accessing the theme
+        #   theme[:input]
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700"
+        #
+        # @example Accessing a validity-specific theme
+        #   theme[:invalid_input]
+        #   # => "bg-red-50 border-red-500 text-red-900 placeholder-red-700 focus:ring-red-500 focus:border-red-500"
+        #
+        # @example Theme inheritance
+        #   theme[:textarea] # Returns :input, indicating textarea inherits input's theme
+        #   theme[:valid_textarea] # Returns :valid_input
+        #
+        # @note The actual content of the theme hash depends on the default_theme method
+        #       and any theme overrides specified in the options when initializing the field builder.
+        #
+        # @see #default_theme
+        def theme
+          @theme ||= options[:theme] || default_theme
+        end
+
+        # Defines and returns the default theme hash for the field builder.
+        #
+        # This method returns a hash containing the base theme definitions for various components.
+        # It sets up the default styling and relationships between different components and their states.
+        # The theme uses a combination of explicit CSS classes and symbolic references to other theme keys,
+        # allowing for a flexible and inheritance-based theming system.
+        #
+        # @return [Hash] A frozen hash containing default theme definitions for components
+        #
+        # @example Accessing the default theme
+        #   default_theme[:input]
+        #   # => nil (indicates that :input doesn't have a default and should be defined by the user)
+        #
+        # @example Theme inheritance
+        #   default_theme[:textarea]
+        #   # => :input (indicates that :textarea inherits from :input)
+        #
+        # @example Validity state theming
+        #   default_theme[:valid_textarea]
+        #   # => :valid_input (indicates that :valid_textarea inherits from :valid_input)
+        #
+        # @note This method returns a frozen hash to prevent accidental modifications.
+        #       To customize the theme, users should provide their own theme hash when initializing the field builder.
+        # @note Most theme values are set to nil or commented out in the default theme to encourage users
+        #       to define their own styles while maintaining the relationships between components and states.
+        #
+        # @see #theme
+        def default_theme
+          {
+            # # input
+            # input: nil,
+            # valid_input: nil,
+            # invalid_input: nil,
+            # neutral_input: nil,
+
+            # textarea
+            textarea: :input,
+            valid_textarea: :valid_input,
+            invalid_textarea: :invalid_input,
+            neutral_textarea: :neutral_input,
+
+            # select
+            select: :input,
+            valid_select: :valid_input,
+            invalid_select: :invalid_input,
+            neutral_select: :neutral_input,
+
+            # file
+            file: :input,
+            valid_file: :valid_input,
+            invalid_file: :invalid_input,
+            neutral_file: :neutral_input,
+
+            # misc
+            # label: nil,
+            # hint: nil,
+            # error: nil,
+            full_error: :error,
+            # wrapper: nil,
+            # inner_wrapper: nil,
+            submit_button: :button
+
+            # # 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
+      end
+    end
+  end
+end

data/lib/phlexi/form/option_mapper.rb

@@ -93,7 +93,7 @@ module Phlexi
         else
           array_to_hash(Array(collection))
         end
-      rescue ArgumentError => e
+      rescue ArgumentError
         # Rails.logger.warn("Unhandled inclusion collection type: #{e}")
         {}
       end
@@ -142,7 +142,7 @@ module Phlexi
 
       # @return [Array<Symbol>] An array of method names to try for collection values.
       def collection_value_methods
-        @collection_value_methods ||= %i[to_param id to_s].freeze
+        @collection_value_methods ||= %i[id to_s].freeze
       end
 
       # @return [Array<Symbol>] An array of method names to try for collection labels.

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

@@ -18,39 +18,44 @@ module Phlexi
         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.
+        # them with a `_` for a DOM ID.
         def id
-          lineage.map(&:key).join("_")
+          @id ||= begin
+            root, *rest = lineage
+            root_key = root.respond_to?(:dom_id) ? root.dom_id : root.key
+            rest.map(&:key).unshift(root_key).join("_")
+          end
         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
+        # The `name` attribute of a node, which is influenced by Rails.
+        # 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
+          @name ||= begin
+            root, *names = keys
+            names.map { |name| "[#{name}]" }.unshift(root).join
+          end
+        end
+
+        # One-liner way of walking from the current node all the way up to the parent.
+        def lineage
+          @lineage ||= Enumerator.produce(@field, &:parent).take_while(&:itself).reverse
         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}/>"
+          "<#{self.class.name} id=#{id.inspect} name=#{name.inspect} value=#{value.inspect}/>"
         end
 
         private
 
         def keys
-          lineage.map do |node|
+          @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? FieldBuilder
           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
   end

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,203 @@ 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
 
+        # Creates a label tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the label.
+        # @return [Components::Label] The label component.
         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)
+          create_component(Components::Label, :label, **attributes)
         end
 
+        # Creates an input tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the input.
+        # @return [Components::Input] The input component.
         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)
+          create_component(Components::Input, :input, **attributes)
         end
 
+        def file_input_tag(**attributes)
+          create_component(Components::FileInput, :file, **attributes)
+        end
+
+        # Creates a checkbox tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the checkbox.
+        # @return [Components::Checkbox] The checkbox component.
         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)
+          create_component(Components::Checkbox, :checkbox, **attributes)
         end
 
+        # 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(**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, &)
+          create_component(Components::CollectionCheckboxes, :collection_checkboxes, **attributes, &)
         end
 
+        # 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(**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)
+          create_component(Components::RadioButton, :radio, **attributes)
         end
 
+        # 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(**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, &)
+          create_component(Components::CollectionRadioButtons, :collection_radio_buttons, **attributes, &)
         end
 
+        # Creates a textarea tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the textarea.
+        # @return [Components::Textarea] The textarea component.
         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)
+          create_component(Components::Textarea, :textarea, **attributes)
         end
 
+        # Creates a select tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the select.
+        # @return [Components::Select] The select component.
         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)
+          create_component(Components::Select, :select, **attributes)
+        end
+
+        def input_array_tag(**attributes)
+          create_component(Components::InputArray, :array, **attributes)
         end
 
+        # Creates a hint tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the hint.
+        # @return [Components::Hint] The hint component.
         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)
+          create_component(Components::Hint, :hint, **attributes)
         end
 
+        # Creates an error tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the error.
+        # @return [Components::Error] The error component.
         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)
+          create_component(Components::Error, :error, **attributes)
         end
 
+        # Creates a full error tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the full error.
+        # @return [Components::FullError] The full error component.
         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)
+          create_component(Components::FullError, :full_error, **attributes)
         end
 
+        # Wraps the field with additional markup.
+        #
+        # @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 = 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, &)
+          Components::Wrapper.new(self, class: wrapper_class, inner: inner, **attributes, &)
         end
 
-        # Wraps a field that's an array of values with a bunch of fields
+        # Creates a multi-value field collection.
         #
-        # @example Usage
-        #
-        # ```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
+        # @param range [Integer, #to_a] The range of keys for each field. If an integer is passed, keys will begin from 1.
+        # @yield [block] The block to be executed for each item in the collection.
+        # @return [FieldCollection] The field collection.
         def multi(range = nil, &)
-          range ||= Array(collection)
-          FieldCollection.new(field: self, range:, &)
+          FieldCollection.new(field: self, range: range, &)
         end
 
-        private
-
-        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(**attributes, &)
+          create_component(Components::SubmitButton, :submit_button, **attributes, &)
         end
 
-        def themed_input(input_component)
-          themed(input_component) || themed(:input) if input_component
-        end
+        def extract_input(params)
+          raise "field##{dom.name} did not define an input component" unless @field_input_component
 
-        def resolve_theme(property)
-          options[property] || theme[property]
+          @field_input_component.extract_input(params)
         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}"
+        protected
+
+        def create_component(component_class, theme_key, **attributes)
+          if component_class.include?(Phlexi::Form::Components::Concerns::HandlesInput)
+            raise "input component already defined: #{@field_input_component.inspect}" if @field_input_component
+
+            attributes = input_attributes.deep_merge(attributes)
+            @field_input_component = component_class.new(self, class: component_class_for(theme_key, attributes), **attributes)
           else
-            :"neutral_#{property}"
+            component_class.new(self, class: component_class_for(theme_key, attributes), **attributes)
           end
+        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
+        def component_class_for(theme_key, attributes)
+          attributes.delete(:class) || themed(attributes.key?(:theme) ? attributes.delete(:theme) : theme_key)
+        end
 
         def has_value?
           value.present?
         end
+
+        def determine_initial_value(value)
+          return value unless value == NIL_VALUE
+
+          determine_from_association || determine_value_from_object
+        end
+
+        def determine_value_from_object
+          object.respond_to?(key) ? object.public_send(key) : nil
+        end
+
+        def determine_from_association
+          return nil unless reflection.present?
+
+          value = object.public_send(key)
+          case reflection.macro
+          when :has_many, :has_and_belongs_to_many
+            value&.map { |v| v.public_send(reflection.klass.primary_key) }
+          when :belongs_to, :has_one
+            value&.public_send(reflection.klass.primary_key)
+          else
+            raise ArgumentError, "Unsupported association type: #{reflection.macro}"
+          end
+        end
       end
     end
   end

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

@@ -7,18 +7,27 @@ module Phlexi
         include Enumerable
 
         class Builder
-          attr_reader :key
+          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|
+            @field.class.new(key, input_attributes: @field.input_attributes, **, 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 +44,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