hakumi_components 0.1.18.pre → 0.1.19.pre

data/app/form_builders/hakumi_components/form_builder.rb

@@ -1,109 +1,96 @@
+# typed: strict
 # frozen_string_literal: true
 
 module HakumiComponents
-  # Custom FormBuilder that renders Hakumi components for form inputs.
-  # Extends Rails' ActionView::Helpers::FormBuilder to integrate seamlessly with Rails forms.
-  # Includes automatic detection of validations, I18n labels, and attribute introspection.
-  #
-  # @example Usage
-  #   <%= hakumi_form_with(model: @user) do |f| %>
-  #     <%= f.text_field :email %>  # Automatically detects label, required, type, etc.
-  #     <%= f.password_field :password %>
-  #     <%= f.text_area :bio %>
-  #     <%= f.submit "Save" %>
-  #   <% end %>
   class FormBuilder < ActionView::Helpers::FormBuilder
-    # Renders a Hakumi text input field with Rails integration
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the input
-    # @return [String] Rendered HTML
+    extend T::Sig
+
+    sig do
+      params(
+        object_name: T.nilable(Types::StringOrSymbol),
+        object: T.nilable(ActiveModel::Model),
+        template: ActionView::Helpers::RenderingHelper,
+        options: Contracts::BuilderInitOptions
+      ).void
+    end
+    def initialize(object_name, object, template, options)
+      @object_name = T.let(object_name&.to_s, T.nilable(String))
+      @object = T.let(object, T.nilable(ActiveModel::Model))
+      @template = T.let(template, ActionView::Helpers::RenderingHelper)
+      @model_binding = T.let(nil, T.nilable(HakumiComponents::FormBuilder::ModelBinding))
+      super
+    end
+
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def text_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::Input::Component, method, **options)
+      render_simple_field(HakumiComponents::Input::Component, method, options)
     end
 
-    # Renders a Hakumi password input field with visibility toggle
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the input
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def password_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::Input::Password::Component, method, **options)
+      render_simple_field(HakumiComponents::Input::Password::Component, method, options)
     end
 
-    # Renders a Hakumi textarea field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the textarea
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def text_area(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::Input::TextArea::Component, method, **options)
+      render_simple_field(HakumiComponents::Input::TextArea::Component, method, options)
     end
 
-    # Renders a Hakumi number input field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the input
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def number_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::InputNumber::Component, method, **options)
+      render_simple_field(HakumiComponents::InputNumber::Component, method, options)
     end
 
-    # Renders a Hakumi select field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param choices [Array] Array of options [[label, value], ...]
-    # @param options [Hash] Options for the select
-    # @return [String] Rendered HTML
+    sig do
+      params(
+        method: Symbol,
+        choices: T.nilable(T::Array[HakumiComponents::SelectionControl::Coercion::FlatOptionInput]),
+        options: Contracts::OptionValue
+      ).returns(ActiveSupport::SafeBuffer)
+    end
     def select(method, choices = nil, **options)
-      choices ||= [] # steep:ignore UnannotatedEmptyCollection
-      enhance_options_with_introspection!(method, options)
-
-      render_form_field(
+      render_collection_field(
         HakumiComponents::Select::Component,
         method,
-        **options.merge(options: choices)
+        :options,
+        HakumiComponents::SelectionControl::Coercion.options(ensure_flat_selection_array(choices)),
+        options
       )
     end
 
-    # Renders a Hakumi tree select field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param choices [Array] Array of tree options with keys: key, title, children
-    # @param options [Hash] Options for the tree select
-    # @return [String] Rendered HTML
+    sig do
+      params(
+        method: Symbol,
+        choices: T.nilable(T::Array[HakumiComponents::SelectionControl::TreeNode]),
+        options: Contracts::OptionValue
+      ).returns(ActiveSupport::SafeBuffer)
+    end
     def tree_select(method, choices = nil, **options)
-      choices ||= [] # steep:ignore UnannotatedEmptyCollection
-      enhance_options_with_introspection!(method, options)
-
-      render_form_field(
+      render_collection_field(
         HakumiComponents::TreeSelect::Component,
         method,
-        **options.merge(options: choices)
+        :options,
+        choices || [],
+        options
       )
     end
 
-    # Renders a Hakumi radio button
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param tag_value [String] Value for this radio button
-    # @param options [Hash] Options for the radio
-    # @return [String] Rendered HTML
+    sig do
+      params(
+        method: Symbol,
+        tag_value: HakumiComponents::Types::FormFieldValue,
+        options: Contracts::OptionValue
+      ).returns(ActiveSupport::SafeBuffer)
+    end
     def radio_button(method, tag_value, **options)
       enhance_options_with_introspection!(method, options)
 
-      # Use tag_value as ID suffix unless explicitly provided
       id_suffix = options[:id] ? nil : tag_value.to_s
       config = field_configuration(method, options, id_suffix: id_suffix)
 
-      # Override with explicit ID if provided
-      config[:id] = options.delete(:id) if options[:id]
+      option_id = options.delete(:id)
+      config[:id] = option_id if option_id.is_a?(String) || option_id.is_a?(Symbol)
 
-      # Determine if checked
       checked = config[:value].to_s == tag_value.to_s
       config[:value] = tag_value
       config[:checked] = checked
@@ -111,72 +98,48 @@ module HakumiComponents
       render_form_field(
         HakumiComponents::Radio::Component,
         method,
-        config_overrides: config,
-        **options
+        options,
+        config
       )
     end
 
-    # Renders a Hakumi radio group from a collection
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param collection [Array] Collection of objects
-    # @param value_method [Symbol] Method to call for value
-    # @param text_method [Symbol] Method to call for label text
-    # @param options [Hash] Options for the radio group
-    # @return [String] Rendered HTML
+    sig do
+      params(
+        method: Symbol,
+        collection: T::Array[T.any(Struct, ActiveModel::Model)],
+        value_method: Symbol,
+        text_method: Symbol,
+        options: Contracts::OptionValue
+      ).returns(ActiveSupport::SafeBuffer)
+    end
     def collection_radio_buttons(method, collection, value_method, text_method, **options)
       enhance_options_with_introspection!(method, options)
 
-      # Convert collection to radio options format (Hash with :label and :value)
       radio_options = collection.map do |item|
-        {
+        HakumiComponents::Radio::Group::Option.new(
           label: item.send(text_method),
           value: item.send(value_method)
-        }
+        )
       end
 
       render_form_field(
         HakumiComponents::Radio::Group::Component,
         method,
-        **options.merge(options: radio_options)
+        options.merge(options: radio_options)
       )
     end
 
-    # Renders a Hakumi switch (checkbox) field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the switch
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def check_box(method, **options)
-      enhance_options_with_introspection!(method, options)
-
-      # Convert truthy/falsy value to boolean for checked attribute
-      value = object_value(method)
-      checked = value ? true : false
-
-      render_form_field(
-        HakumiComponents::Switch::Component,
-        method,
-        config_overrides: { checked: checked },
-        **options
-      )
+      render_checked_field(HakumiComponents::Switch::Component, method, options)
     end
 
-    # Renders a Hakumi rate (rating) field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the rate component
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def rate_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::Rate::Component, method, **options)
+      render_simple_field(HakumiComponents::Rate::Component, method, options)
     end
 
-    # Renders a Hakumi slider field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the slider component
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def slider_field(method, **options)
       enhance_options_with_introspection!(method, options)
 
@@ -185,160 +148,103 @@ module HakumiComponents
       render_form_field(
         HakumiComponents::Slider::Component,
         method,
-        config_overrides: config,
-        **options
+        options,
+        config
       )
     end
 
-    # Renders a Hakumi date picker field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the date picker
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def date_picker(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::DatePicker::Component, method, **options)
-    end
-
-    # Renders a Hakumi mentions field (textarea with @ mention suggestions)
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the mentions component
-    # @option options [Array] :options Array of mention options (names, usernames, etc.)
-    # @option options [String, Array] :prefix Character(s) that trigger mentions (default: "@")
-    # @option options [String] :split Character that separates tokens (default: " ")
-    # @option options [Symbol] :filter_option Filter mode (:contains, :starts_with)
-    # @return [String] Rendered HTML
-    def mentions_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-
-      # Extract mentions-specific options before field configuration
-      mention_options = options.delete(:options) || []
+      render_simple_field(HakumiComponents::DatePicker::Component, method, options)
+    end
 
-      render_form_field(
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
+    def mentions_field(method, **options)
+      render_collection_field(
         HakumiComponents::Mentions::Component,
         method,
-        **options.merge(options: mention_options)
+        :options,
+        HakumiComponents::Mentions::Coercion.options(ensure_mentions_array(options.delete(:options))),
+        options
       )
     end
 
-    # Renders a Hakumi autocomplete field (input with dropdown suggestions)
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param choices [Array] Array of autocomplete options
-    # @param options [Hash] Options for the autocomplete component
-    # @return [String] Rendered HTML
+    sig do
+      params(
+        method: Symbol,
+        choices: T.nilable(T::Array[HakumiComponents::SelectionControl::Coercion::EntryInput]),
+        options: Contracts::OptionValue
+      ).returns(ActiveSupport::SafeBuffer)
+    end
     def autocomplete_field(method, choices = nil, **options)
-      choices ||= [] # steep:ignore UnannotatedEmptyCollection
-      enhance_options_with_introspection!(method, options)
-
-      render_form_field(
+      render_collection_field(
         HakumiComponents::Autocomplete::Component,
         method,
-        **options.merge(options: choices)
+        :options,
+        HakumiComponents::SelectionControl::Coercion.entries(ensure_selection_entry_array(choices)),
+        options
       )
     end
 
-    # Renders a Hakumi cascader field (cascading dropdown selector)
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param choices [Array] Array of cascader options with children
-    # @param options [Hash] Options for the cascader component
-    # @return [String] Rendered HTML
+    sig do
+      params(
+        method: Symbol,
+        choices: T.nilable(T::Array[HakumiComponents::SelectionControl::TreeNode]),
+        options: Contracts::OptionValue
+      ).returns(ActiveSupport::SafeBuffer)
+    end
     def cascader_field(method, choices = nil, **options)
-      choices ||= [] # steep:ignore UnannotatedEmptyCollection
-      enhance_options_with_introspection!(method, options)
-
-      render_form_field(
+      render_collection_field(
         HakumiComponents::Cascader::Component,
         method,
-        **options.merge(options: choices)
+        :options,
+        choices || [],
+        options
       )
     end
 
-    # Renders a Hakumi checkbox field (traditional checkbox, different from switch)
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the checkbox
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def checkbox_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-
-      # Convert truthy/falsy value to boolean for checked attribute
-      value = object_value(method)
-      checked = value ? true : false
-
-      render_form_field(
-        HakumiComponents::Checkbox::Component,
-        method,
-        config_overrides: { checked: checked },
-        **options
-      )
+      render_checked_field(HakumiComponents::Checkbox::Component, method, options)
     end
 
-    # Renders a Hakumi color picker field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the color picker component
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def color_picker_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::ColorPicker::Component, method, **options)
+      render_simple_field(HakumiComponents::ColorPicker::Component, method, options)
     end
 
-    # Renders a Hakumi time picker field
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the time picker component
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def time_picker_field(method, **options)
-      enhance_options_with_introspection!(method, options)
-      render_form_field(HakumiComponents::TimePicker::Component, method, **options)
+      render_simple_field(HakumiComponents::TimePicker::Component, method, options)
     end
 
-    # Renders a Hakumi transfer field (dual list box)
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param data_source [Array] Array of items to transfer
-    # @param options [Hash] Options for the transfer component
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, data_source: T.nilable(T::Array[HakumiComponents::Transfer::Coercion::ItemInput]), options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def transfer_field(method, data_source = nil, **options)
-      data_source ||= [] # steep:ignore UnannotatedEmptyCollection
-      enhance_options_with_introspection!(method, options)
-
-      render_form_field(
+      disabled = options[:disabled] == true
+      render_collection_field(
         HakumiComponents::Transfer::Component,
         method,
-        **options.merge(data_source: data_source)
+        :data_source,
+        HakumiComponents::Transfer::Coercion.items(Array(data_source), disabled: disabled),
+        options
       )
     end
 
-    # Renders a Hakumi upload field (file upload)
-    #
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the upload component
-    # @option options [String] :action Upload URL (required)
-    # @return [String] Rendered HTML
+    sig { params(method: Symbol, options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def upload_field(method, **options)
       enhance_options_with_introspection!(method, options)
 
-      # Upload requires action parameter
       raise ArgumentError, "action parameter is required for upload_field" unless options[:action]
 
-      render_form_field(HakumiComponents::Upload::Component, method, **options)
+      render_form_field(HakumiComponents::Upload::Component, method, options)
     end
 
-    # Renders a Hakumi submit button
-    #
-    # @param value [String] Button text (defaults to "Save")
-    # @param options [Hash] Options for the button
-    # @return [String] Rendered HTML
+    sig { params(value: T.nilable(String), options: Contracts::OptionValue).returns(ActiveSupport::SafeBuffer) }
     def submit(value = nil, **options)
       value ||= submit_default_value
 
-      # Extract Hakumi-specific options
       button_type = options.delete(:type) || :primary
-      button_size = options.delete(:size) || :middle
+      button_size = options.delete(:size) || :default
       block = options.delete(:block) || false
       loading = options.delete(:loading) || false
       danger = options.delete(:danger) || false
@@ -356,127 +262,142 @@ module HakumiComponents
 
     private
 
-    # Gets standard field configuration (name, id, value, errors)
-    #
-    # @param method [Symbol] Attribute name
-    # @param options [Hash] Options hash (modifies in place by deleting :value)
-    # @param id_suffix [String, nil] Optional suffix for field_id (for radio buttons)
-    # @return [Hash] Field configuration with :name, :id, :value, :errors
-    def field_configuration(method, options, id_suffix: nil)
-      field_name = @object_name ? "#{@object_name}[#{method}]" : method.to_s
-
-      base_id = @object_name ? "#{@object_name}_#{method}" : method.to_s
-      field_id = id_suffix ? "#{base_id}_#{id_suffix}".parameterize.underscore : base_id
+    sig { params(component_class: T.class_of(ViewComponent::Base), method: Symbol, options: Contracts::OptionsHash).returns(ActiveSupport::SafeBuffer) }
+    def render_simple_field(component_class, method, options)
+      enhance_options_with_introspection!(method, options)
+      render_form_field(component_class, method, options)
+    end
 
-      value = options.delete(:value) || object_value(method)
-      errors = object_errors(method)
+    sig do
+      params(
+        component_class: T.class_of(ViewComponent::Base),
+        method: Symbol,
+        collection_key: Symbol,
+        collection: T.nilable(Contracts::MixedCollection),
+        options: Contracts::OptionsHash
+      ).returns(ActiveSupport::SafeBuffer)
+    end
+    def render_collection_field(component_class, method, collection_key, collection, options)
+      enhance_options_with_introspection!(method, options)
+      options[collection_key] = collection || []
+      render_form_field(component_class, method, options)
+    end
 
-      {
-        name: field_name,
-        id: field_id,
-        value: value,
-        errors: errors
-      }
+    sig { params(component_class: T.class_of(ViewComponent::Base), method: Symbol, options: Contracts::OptionsHash).returns(ActiveSupport::SafeBuffer) }
+    def render_checked_field(component_class, method, options)
+      enhance_options_with_introspection!(method, options)
+      checked = !!model_binding.value_for(method)
+      render_form_field(component_class, method, options, { checked: checked })
     end
 
-    # Enhances options hash with automatic detection from Rails validations and I18n
-    #
-    # @param method [Symbol] Attribute name
-    # @param options [Hash] Options hash to enhance
-    # @return [Hash] Enhanced options
-    def enhance_options_with_introspection!(method, options)
-      return unless @object
+    sig do
+      params(
+        value: T.nilable(T::Array[HakumiComponents::SelectionControl::Coercion::FlatOptionInput])
+      ).returns(T::Array[HakumiComponents::SelectionControl::Coercion::FlatOptionInput])
+    end
+    def ensure_flat_selection_array(value)
+      value || []
+    end
 
-      # Auto-detect label from I18n (if not provided)
-      if options[:label].nil?
-        detected_label = HakumiComponents::Rails::AttributeIntrospection.human_attribute_name(@object, method)
-        options[:label] = detected_label if detected_label
-      end
+    sig do
+      params(
+        value: T.nilable(T::Array[HakumiComponents::SelectionControl::Coercion::EntryInput])
+      ).returns(T::Array[HakumiComponents::SelectionControl::Coercion::EntryInput])
+    end
+    def ensure_selection_entry_array(value)
+      value || []
+    end
 
-      # Auto-detect required for UI purposes (asterisk display) - NOT for HTML5 validation
-      if options[:required].nil?
-        options[:required] = HakumiComponents::Rails::ValidationIntrospection.required?(@object, method)
-      end
+    sig { params(value: T.nilable(Contracts::OptionValue)).returns(T::Array[HakumiComponents::Mentions::Coercion::OptionInput]) }
+    def ensure_mentions_array(value)
+      return [] if value.nil?
+      return value.filter_map { |item| mentions_option_input(item) } if value.is_a?(Array)
 
-      # Auto-detect placeholder from I18n (if not provided)
-      if options[:placeholder].nil?
-        detected_placeholder = HakumiComponents::Rails::AttributeIntrospection.placeholder(@object, method)
-        options[:placeholder] = detected_placeholder if detected_placeholder
-      end
+      single_value = mentions_option_input(value)
+      single_value.nil? ? [] : [ single_value ]
+    end
 
-      # Auto-detect caption (hint) from I18n (if not provided)
-      if options[:caption].nil?
-        detected_hint = HakumiComponents::Rails::AttributeIntrospection.hint(@object, method)
-        options[:caption] = detected_hint if detected_hint
-      end
+    sig { params(value: Contracts::OptionValue).returns(T.nilable(HakumiComponents::Mentions::Coercion::OptionInput)) }
+    def mentions_option_input(value)
+      case value
+      when HakumiComponents::Mentions::Option, String, Symbol, Numeric
+        value
+      when Hash
+        mention_hash = T.let({}, T::Hash[T.any(Symbol, String), T.nilable(T.any(String, Symbol, Numeric))])
+        value.each do |key, item|
+          return nil unless item.nil? || item.is_a?(String) || item.is_a?(Symbol) || item.is_a?(Numeric)
+
+          mention_hash[key] = item
+        end
+        mention_hash
+      when Array
+        mention_array = T.let([], T::Array[T.nilable(T.any(String, Symbol, Numeric))])
+        value.each do |item|
+          return nil unless item.nil? || item.is_a?(String) || item.is_a?(Symbol) || item.is_a?(Numeric)
 
-      # Auto-generate frontend validation rules from Rails validations
-      # If manual rules are provided, merge them with auto-detected rules
-      # Manual rules take priority over auto-detected ones for the same validation type
-      detected_rules = HakumiComponents::Rails::ValidationMapper.to_frontend_rules(@object, method)
-      manual_rules = options[:rules]
-
-      if manual_rules.nil?
-        options[:rules] = detected_rules unless detected_rules.empty?
-      elsif !detected_rules.empty?
-        # Merge manual and auto-detected rules, with manual rules taking priority
-        options[:rules] = HakumiComponents::Rails::ValidationMapper.merge_rules(manual_rules, detected_rules)
-      end
-      # If manual_rules is present but detected_rules is empty, keep manual_rules as-is
-
-      # Auto-detect input type based on attribute name and validations (if not provided)
-      if options[:type].nil?
-        if HakumiComponents::Rails::ValidationIntrospection.email_field?(@object, method)
-          options[:type] = :email
-        elsif HakumiComponents::Rails::ValidationIntrospection.url_field?(@object, method)
-          options[:type] = :url
-        else
-          # Fallback to column type
-          detected_type = HakumiComponents::Rails::AttributeIntrospection.input_type_from_column(@object, method)
-          options[:type] = detected_type if detected_type && detected_type != :text
+          mention_array << item
         end
+        mention_array
+      else
+        nil
       end
+    end
+
+    sig do
+      params(
+        method: Symbol,
+        options: Contracts::OptionsHash,
+        id_suffix: T.nilable(String)
+      ).returns(HakumiComponents::Types::FormFieldConfig)
+    end
+    def field_configuration(method, options, id_suffix: nil)
+      explicit_value = normalize_form_field_value(options.delete(:value))
+      model_binding.build_field_context(method: method, explicit_value: explicit_value, id_suffix: id_suffix).to_options
+    end
 
-      options
+    sig { params(method: Symbol, options: Contracts::OptionsHash).returns(Contracts::OptionsHash) }
+    def enhance_options_with_introspection!(method, options)
+      enhanced = model_binding.enhance_options(method: method, options: options)
+      options.replace(enhanced)
     end
 
-    # Renders a form field component with Rails integration
-    #
-    # @param component_class [Class] Component class to render
-    # @param method [Symbol] Name of the attribute
-    # @param options [Hash] Options for the component
-    # @param config_overrides [Hash] Override field configuration (for special cases)
-    # @return [String] Rendered HTML
-    def render_form_field(component_class, method, config_overrides: {}, **options)
+    sig do
+      params(
+        component_class: T.class_of(ViewComponent::Base),
+        method: Symbol,
+        options: Contracts::OptionsHash,
+        config_overrides: Contracts::OptionsHash
+      ).returns(ActiveSupport::SafeBuffer)
+    end
+    def render_form_field(component_class, method, options, config_overrides = {})
       config = field_configuration(method, options)
       config.merge!(config_overrides)
 
-      # Merge all options with standalone: false
       component_options = config.merge(options).merge(standalone: false)
 
-      # Render the component with merged configuration
       @template.render(component_class.new(**component_options))
     end
 
-    # Gets the current value of an attribute from the object
-    #
-    # @param method [Symbol] Attribute name
-    # @return [Object] Current value
-    def object_value(method)
-      @object.respond_to?(method) ? @object.public_send(method) : nil
+    sig { params(value: T.nilable(Contracts::OptionValue)).returns(HakumiComponents::Types::FormFieldValue) }
+    def normalize_form_field_value(value)
+      case value
+      when nil, String, Symbol, TrueClass, FalseClass, Numeric, Date, Time, DateTime, ActiveSupport::TimeWithZone, ActiveSupport::SafeBuffer
+        value
+      when Array
+        value.filter_map do |item|
+          case item
+          when nil, String, Symbol, TrueClass, FalseClass, Numeric, Date, Time, DateTime, ActiveSupport::TimeWithZone, ActiveSupport::SafeBuffer
+            item
+          end
+        end
+      else
+        nil
+      end
     end
 
-    # Gets validation errors for an attribute from the object
-    # Uses full_messages_for to include attribute name in error messages
-    #
-    # @param method [Symbol] Attribute name
-    # @return [Array<String>] Array of error messages
-    def object_errors(method)
-      return [] unless @object.respond_to?(:errors)
-
-      # Use full_messages_for which includes the attribute name
-      # e.g., "Email can't be blank" instead of "can't be blank"
-      @object.errors.full_messages_for(method)
+    sig { returns(HakumiComponents::FormBuilder::ModelBinding) }
+    def model_binding
+      @model_binding ||= HakumiComponents::FormBuilder::ModelBinding.new(object_name: @object_name, object: @object)
     end
   end
 end