### Example HyperActiveForm Object

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Demonstrates how to define a form object using HyperActiveForm, including proxying to a model, defining attributes with types, setting up validations, pre-filling data via `setup`, and performing the form's business logic in `perform`.

```Ruby
class ProfileForm < ApplicationForm
  # proxy_for is used to delegate the model name to the class, and some methods to the object
  # this helps use `form_with` in views without having to specify the url
  proxy_for User, :@user

  # Define the form fields, using ActiveModel::Attributes
  attribute :first_name
  attribute :last_name
  attribute :birth_date, :date

  # Define the validations, using ActiveModel::Validations
  validates :first_name, presence: true
  validates :last_name, presence: true
  validates :birth_date, presence: true

  # Pre-fill the form if needed
  def setup(user)
    @user = user
    self.first_name = user.first_name
    self.last_name = user.last_name
    self.birth_date = user.birth_date
  end

  # Perform the form logic
  def perform
    @user.update!(
      first_name: first_name,
      last_name: last_name,
      birth_date: birth_date
    )
  end
end
```

--------------------------------

### Example ProfileForm Object

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

A comprehensive example of a HyperActiveForm form object, demonstrating attribute definition, validations, setup for pre-filling data, and the perform method for business logic.

```ruby
class ProfileForm < ApplicationForm
  # proxy_for is used to delegate the model name to the class, and some methods to the object
  # this helps use `form_with` in views without having to specify the url
  proxy_for User, :@user

  # Define the form fields, using ActiveModel::Attributes
  attribute :first_name
  attribute :last_name
  attribute :birth_date, :date

  # Define the validations, using ActiveModel::Validations
  validates :first_name, presence: true
  validates :last_name, presence: true
  validates :birth_date, presence: true

  # Pre-fill the form if needed
  def setup(user)
    @user = user
    self.first_name = user.first_name
    self.last_name = user.last_name
    self.birth_date = user.birth_date
  end

  # Perform the form logic
  def perform
    @user.update!(
      first_name: first_name,
      last_name: last_name,
      birth_date: birth_date
    )
  end
end
```

--------------------------------

### Understanding setup in HyperActiveForm

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Details the `setup` method in HyperActiveForm, which is called immediately after form initialization. It's used to pre-fill the form fields with data from an associated object, receiving the same arguments as the form's initializer.

```APIDOC
setup(args...)
  - Called after the form is initialized.
  - Used to pre-fill form fields with data from an associated object.
  - Receives the same arguments passed to the form's initializer.
  - Parameters:
    - args: Arguments passed during form initialization.
  - Example:
    class ProfileForm < ApplicationForm
      def setup(user)
        @user = user
        self.first_name = user.first_name
        self.last_name = user.last_name
        self.birth_date = user.birth_date
      end
    end
```

--------------------------------

### Example HyperActiveForm Object

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Demonstrates how to define a form object using HyperActiveForm, including proxying to a model, defining attributes with types, setting up validations, pre-filling data via `setup`, and performing the form's business logic in `perform`.

```Ruby
class ProfileForm < ApplicationForm
  # proxy_for is used to delegate the model name to the class, and some methods to the object
  # this helps use `form_with` in views without having to specify the url
  proxy_for User, :@user

  # Define the form fields, using ActiveModel::Attributes
  attribute :first_name
  attribute :last_name
  attribute :birth_date, :date

  # Define the validations, using ActiveModel::Validations
  validates :first_name, presence: true
  validates :last_name, presence: true
  validates :birth_date, presence: true

  # Pre-fill the form if needed
  def setup(user)
    @user = user
    self.first_name = user.first_name
    self.last_name = user.last_name
    self.birth_date = user.birth_date
  end

  # Perform the form logic
  def perform
    @user.update!(
      first_name: first_name,
      last_name: last_name,
      birth_date: birth_date
    )
  end
end
```

--------------------------------

### Understanding setup in HyperActiveForm

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Details the `setup` method in HyperActiveForm, which is called immediately after form initialization. It's used to pre-fill the form fields with data from an associated object, receiving the same arguments as the form's initializer.

```APIDOC
setup(args...)
  - Called after the form is initialized.
  - Used to pre-fill form fields with data from an associated object.
  - Receives the same arguments passed to the form's initializer.
  - Parameters:
    - args: Arguments passed during form initialization.
  - Example:
    class ProfileForm < ApplicationForm
      def setup(user)
        @user = user
        self.first_name = user.first_name
        self.last_name = user.last_name
        self.birth_date = user.birth_date
      end
    end
```

--------------------------------

### HyperActiveForm DSL: setup

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Details the `setup` method, a callback executed immediately after form initialization. It's designed for pre-filling form attributes with data from an associated model object, receiving the same arguments as the form's initializer.

```APIDOC
setup(args...)
  - Purpose: Pre-fills form attributes with data from an object.
  - Trigger: Called automatically after form initialization.
  - Arguments: Receives the same arguments passed to the form's initializer.
  - Behavior:
    - Assigns values to form attributes (e.g., `self.first_name = user.first_name`).
    - Typically used to populate the form with existing data from a model.
  - Example:
    class ProfileForm < ApplicationForm
      def setup(user)
        @user = user
        self.first_name = user.first_name
        self.last_name = user.last_name
        self.birth_date = user.birth_date
      end
    end
```

--------------------------------

### setup Instance Method - HyperActiveForm::Base

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

A hook method called during initialization, intended for subclasses to perform custom setup tasks. It receives any arguments passed to the constructor.

```Ruby
def setup
  # ... implementation details ...
end
```

--------------------------------

### Run HyperActiveForm Install Generator

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Command to run the installation generator for HyperActiveForm, which creates an ApplicationForm base class in your app/forms directory.

```bash
$ bundle install
$ rails generate hyper_active_form:install
```

--------------------------------

### Install HyperActiveForm Gem

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Instructions for adding the HyperActiveForm gem to your Rails application's Gemfile and running the necessary commands to install it and generate the base ApplicationForm class.

```bash
gem 'hyperactiveform'

$ bundle install

$ rails generate hyper_active_form:install
```

--------------------------------

### Install HyperActiveForm Gem

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Instructions for adding the HyperActiveForm gem to your Rails application's Gemfile and installing it via Bundler.

```ruby
gem 'hyperactiveform'
```

--------------------------------

### Install HyperActiveForm Gem

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Instructions for adding the HyperActiveForm gem to your Rails application's Gemfile and running the necessary commands to install it and generate the base ApplicationForm class.

```bash
gem 'hyperactiveform'

$ bundle install

$ rails generate hyper_active_form:install
```

--------------------------------

### HyperActiveForm Search Form Example

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Demonstrates a form object that encapsulates search logic without directly mapping to a single model. The perform method executes the search query and stores results in an instance variable.

```Ruby
class UserSearchForm < ApplicationForm
  attribute :name
  attribute :email
  attribute :min_age, :integer

  attr_reader :results # Allows controller to access search results

  def perform
    @results = User.all

    @results = @results.where(name: name) if name.present?
    @results = @results.where(email: email) if email.present?
    @results = @results.where("age >= ?", min_age) if min_age.present?

    true # Indicate successful execution of search logic
  end
end
```

--------------------------------

### initialize Constructor - HyperActiveForm::Base

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

Initializes a new instance of the Base class, calling the setup method with any provided arguments. This is the primary constructor for creating new form objects.

```Ruby
def initialize(*, **)
  super()
  setup(*, **)
end
```

--------------------------------

### Controller Usage for ProfileForm

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Example controller actions (edit and update) demonstrating how to instantiate and use a HyperActiveForm object with Rails' controller conventions.

```ruby
class UsersController < ApplicationController

  def edit
    @form = ProfileForm.new(user: current_user)
  end

  def update
    @form = ProfileForm.new(user: current_user)
    if @form.submit(params[:user])
      redirect_to root_path, notice: "Profile updated"
    else
      render :edit, status: :unprocessable_entity
    end
  end
end
```

--------------------------------

### Define ContactForm Model in Ruby

Source: https://github.com/intrepidd/hyperactiveform/blob/main/examples/basic.md

Defines a form object for managing contact data, including attributes, validations, and methods for setup and data persistence. It proxies attributes from a Contact model and uses Rails validation mechanisms.

```ruby
class ContactForm < ApplicationForm
  proxy_for Contact, :@contact

  attribute :first_name
  attribute :last_name
  attribute :birth_date, :date

  validates :first_name, presence: true
  validates :last_name, presence: true
  validates :birth_date, presence: true


  def setup(contact)
    @contact = contact
    self.first_name = @contact.first_name
    self.last_name = @contact.last_name
    self.birth_date = @contact.birth_date
    ## You could also do :
    # self.attributes = @contact.attributes.slice(:first_name, :last_name, birth_date)
  end

  def perform
    @contact.update!(
      first_name:,
      last_name:,
      birth_date:
    )
  end
end
```

--------------------------------

### HyperActiveForm Search Form Example

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Demonstrates a form object that encapsulates search logic without directly mapping to a single model. The perform method executes the search query and stores results in an instance variable.

```Ruby
class UserSearchForm < ApplicationForm
  attribute :name
  attribute :email
  attribute :min_age, :integer

  attr_reader :results # Allows controller to access search results

  def perform
    @results = User.all

    @results = @results.where(name: name) if name.present?
    @results = @results.where(email: email) if email.present?
    @results = @results.where("age >= ?", min_age) if min_age.present?

    true # Indicate successful execution of search logic
  end
end
```

--------------------------------

### View Usage with form_with

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Example ERB view code showing how to render a form using Rails' `form_with` helper with a HyperActiveForm object.

```erb
<%= form_with(model: @form) do |f| %>
  <%= f.text_field :first_name %>
  <%= f.text_field :last_name %>
  <%= f.date_field :birth_date %>

  <%= f.submit %>
<% end %>
```

--------------------------------

### Using Search Form in Controller

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

An example of how to instantiate and submit a search form object within a Rails controller, and then access the search results.

```Ruby
class UsersController < ApplicationController
  def index
    @form = UserSearchForm.new
    # Submit the form with parameters from the request.
    @form.submit!(params[:user])
    # Access the results populated by the form's perform method.
    @users = @form.results
  end
end
```

--------------------------------

### Using Search Form in Controller

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

An example of how to instantiate and submit a search form object within a Rails controller, and then access the search results.

```Ruby
class UsersController < ApplicationController
  def index
    @form = UserSearchForm.new
    # Submit the form with parameters from the request.
    @form.submit!(params[:user])
    # Access the results populated by the form's perform method.
    @users = @form.results
  end
end
```

--------------------------------

### Create Search Forms with HyperActiveForm (Ruby)

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Illustrates how to create flexible search forms using HyperActiveForm that encapsulate search logic and do not necessarily map to a single database model. This example shows defining attributes for search criteria and performing the search within the form.

```ruby
class UserSearchForm < ApplicationForm
  attribute :name
  attribute :email
  attribute :min_age, :integer

  attr_reader :results # So the controller can access the results

  def perform
    @results = User.all

    if name.present?
      @results = @results.where(name: name)
    end
    if email.present?
      @results = @results.where(email: email)
    end
    if age.present?
      @results = @results.where("age >= ?", age)
    end

    true
  end
end
```

--------------------------------

### View Usage with form_with

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

An example of how to render a form in a Rails view using the `form_with` helper, bound to a HyperActiveForm object. It includes fields for first name, last name, and birth date, along with a submit button.

```erb
<%= form_with(model: @form) do |f| %>
  <%= f.text_field :first_name %>
  <%= f.text_field :last_name %>
  <%= f.date_field :birth_date %>

  <%= f.submit %>
<% end %>
```

--------------------------------

### Use Search Form in Controller with HyperActiveForm (Ruby)

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Shows a practical example of integrating a HyperActiveForm search form within a Rails controller. It covers initializing the form, submitting parameters, and accessing the search results for display.

```ruby
class UsersController < ApplicationController
  def index
    @form = UserSearchForm.new
    @form.submit!(params[:user])
    @users = @form.results
  end
end
```

--------------------------------

### Manage Contact Form in Rails Controller (Ruby)

Source: https://github.com/intrepidd/hyperactiveform/blob/main/examples/basic.md

Handles form creation, submission, and updates for Contact records within a Rails application. It instantiates the ContactForm, processes form submissions, and manages redirects or renders.

```ruby
class ContactsController
  def new
    @form = ContactForm.new(Contact.new)
  end

  def create
    @form = ContactForm.new(Contact.new)

    if @form.submit(params[:contact])
      redirect_to root_path, notice: "Contact created"
    else
      render :new, status: :unprocessable_entity
    end
  end

  def edit
    @contact = Contact.find(params[:id])
    @form = ContactForm.new(@contact)
  end

  def update
    @contact = Contact.find(params[:id])
    @form = ContactForm.new(@contact)

    if @form.submit(params[:contact])
      redirect_to root_path, notice: "Contact updated"
    else
      render :edit, status: :unprocessable_entity
    end
  end
end
```

--------------------------------

### View Usage with form_with

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

An example of how to render a form in a Rails view using the `form_with` helper, bound to a HyperActiveForm object. It includes fields for first name, last name, and birth date, along with a submit button.

```erb
<%= form_with(model: @form) do |f| %>
  <%= f.text_field :first_name %>
  <%= f.text_field :last_name %>
  <%= f.date_field :birth_date %>

  <%= f.submit %>
<% end %>
```

--------------------------------

### Render Form Partial in Rails Views (ERB)

Source: https://github.com/intrepidd/hyperactiveform/blob/main/examples/basic.md

Renders a shared form partial for both new and edit actions in a Rails application. It passes the form object to the partial for rendering form fields and submission.

```erb
<%= render "form", form: @form %>
```

--------------------------------

### Define Form Fields in Rails Form Partial (ERB)

Source: https://github.com/intrepidd/hyperactiveform/blob/main/examples/basic.md

Defines the HTML structure for a form using Rails' form_with helper. It includes text fields for first name and last name, a date field for birth date, and a submit button.

```erb
<%= form_with(model: form) do |f| %>
  <%= f.text_field :first_name, placeholder: "First name" %>
  <%= f.text_field :last_name, placeholder: "Last name" %>
  <%= f.date_field :birth_date %>
  <%= f.submit "Save" %>
<% end %>
```

--------------------------------

### HyperActiveForm::Generators::InstallGenerator Methods

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/method_list.html

Documentation for methods within the HyperActiveForm::Generators::InstallGenerator class, specifically related to creating application forms.

```APIDOC
#create_application_form
  Generates the application form structure.
  This method is part of the installation generator process.
```

--------------------------------

### HyperActiveForm::Base Methods

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/method_list.html

Documentation for instance and class methods within the HyperActiveForm::Base class. This includes methods for managing form attributes, errors, and submission logic.

```APIDOC
#add_errors_from(errors)
  Adds errors from another object or hash to the current form.
  Parameters:
    errors: An object or hash containing errors to be added.

#assign_form_attributes(attributes)
  Assigns attributes to the form instance.
  Parameters:
    attributes: A hash of attributes to assign.

#assigned_attribute_names
  Returns a list of attribute names that have been assigned to the form.
  Returns:
    Array of strings representing attribute names.

#initialize
  Initializes a new instance of HyperActiveForm::Base.

#perform
  Executes the main logic or action associated with the form.

proxy_for(object)
  Class method to create a proxy object for a given object.
  Parameters:
    object: The object to create a proxy for.
  Returns:
    A proxy object.

#setup
  Performs setup operations for the form instance.

#submit
  Submits the form, typically performing validation and saving data.

#submit!
  Submits the form, potentially raising exceptions on failure.
```

--------------------------------

### HyperactiveForm Base Methods

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

Documentation for core methods of the HyperactiveForm base class. This includes methods for assigning form attributes, handling form submission, and defining abstract methods.

```APIDOC
assign_form_attributes(params)
  Assigns the attributes of the form from the params. This method is called by the 'submit' method, but can also be called directly if you need to assign the attributes without submitting the form (e.g., to refresh the form with new data).
  Parameters:
    params (Hash) — the params to assign the attributes from.
  
  Example:
  assign_form_attributes({ name: 'John Doe', email: 'john.doe@example.com' })
  
  Dependencies:
  Requires ActionController::Parameters if params is not already an instance of it.
  
  Returns:
  Object (implicitly, the form instance itself after attributes are set)
  
  Related Methods:
  submit, submit!

```

```APIDOC
perform
  Abstract method that must be implemented by subclasses to define the form's core logic.
  
  Raises:
  NotImplementedError: If the method is called directly on the base class without being overridden.
  
  Example:
  # In a subclass:
  # def perform
  #   # Your form submission logic here
  # end
  
  Related Methods:
  submit, submit!

```

```APIDOC
setup
  Placeholder method for any setup logic required before form submission or attribute assignment.
  
  Example:
  # In a subclass:
  # def setup
  #   # Initialize specific variables or perform pre-checks
  # end
  
  Related Methods:
  assign_form_attributes, submit, submit!

```

```APIDOC
submit(params)
  Submits the form. This method assigns attributes from params, runs validations, and calls the 'perform' method if the form is valid.
  
  Parameters:
    params (Hash) — the params to assign the attributes from.
  
  Returns:
    Boolean — true if the form is valid and the 'perform' method returned something truthy, false otherwise.
  
  Exceptions:
    HyperActiveForm::CancelFormSubmit: Caught and returns false.
  
  Example:
  # if form.submit(user_params)
  #   # Handle success
  # else
  #   # Handle failure (e.g., display errors)
  # end
  
  Related Methods:
  assign_form_attributes, perform, submit!

```

```APIDOC
submit!(params)
  Submits the form, similar to 'submit', but raises a 'FormDidNotSubmitError' if the form is not valid.
  
  Parameters:
    params (Hash) — the params to assign the attributes from.
  
  Returns:
    Boolean — true if the form is valid and the 'perform' method returned something truthy.
  
  Raises:
    HyperActiveForm::FormDidNotSubmitError: If the form is not valid.
  
  Example:
  # begin
  #   form.submit!(user_params)
  #   # Handle success
  # rescue HyperActiveForm::FormDidNotSubmitError => e
  #   # Handle validation errors or submission failure
  # end
  
  Related Methods:
  submit

```

--------------------------------

### FormGenerator Methods

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/method_list.html

Documentation for methods within the FormGenerator class, focusing on the creation of application forms.

```APIDOC
#create_application_form
  Generates the application form.
  This method is used by form generation utilities.
```

--------------------------------

### TestUnit::Generators::FormGenerator Methods

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/method_list.html

Documentation for methods within the TestUnit::Generators::FormGenerator class, specifically for creating Test::Unit form tests.

```APIDOC
#create_form_test
  Generates a Test::Unit test case for a form.
  This method is part of the Test::Unit generator for forms.
```

--------------------------------

### TestUnit Module Definition

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/TestUnit.html

Details the definition and location of the TestUnit module. This entry describes the module itself, its origin file, and its namespace.

```APIDOC
Module: TestUnit
  Defined in: lib/generators/test_unit/form_generator.rb
  Defined Under Namespace:
    Modules: [Generators](TestUnit::Generators.html "TestUnit::Generators (module)")
  Generated on: Mon Jan 13 17:26:04 2025 by yard 0.9.37 (ruby-3.3.1).
```

--------------------------------

### Controller Usage for Profile Form

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Shows how to instantiate and handle a HyperActiveForm object within a Rails controller for editing and updating user profiles. It covers initializing the form, submitting parameters, and handling success or failure responses.

```Ruby
class UsersController < ApplicationController

  def edit
    @form = ProfileForm.new(user: current_user)
  end

  def update
    @form = ProfileForm.new(user: current_user)
    if @form.submit(params[:user])
      redirect_to root_path, notice: "Profile updated"
    else
      render :edit, status: :unprocessable_entity
    end
  end
end
```

--------------------------------

### Create Application Form Generator

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Generators/InstallGenerator.html

Generates the application_form.rb file in the app/forms directory. This file serves as a base class for custom forms within the HyperActiveForm framework.

```Ruby
class ApplicationForm < HyperActiveForm::Base
end
```

--------------------------------

### Understanding proxy_for in HyperActiveForm

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Explains the `proxy_for` method in HyperActiveForm, detailing how it delegates model name and object instance variables. This is crucial for Rails' `form_for` or `form_with` to correctly determine URLs and HTTP methods based on the form object's associated model.

```APIDOC
proxy_for(model_class, instance_variable_name)
  - Delegates model name and object instance to the specified class and variable.
  - Enables Rails form helpers to infer URLs and HTTP methods.
  - Parameters:
    - model_class: The class of the associated model (e.g., User).
    - instance_variable_name: The name of the instance variable holding the model object (e.g., :@user).
  - Example:
    class ProfileForm < ApplicationForm
      proxy_for User, :@user # Will delegate to @user
    end
  - Note: If URL and method are explicitly passed to form helpers, proxy_for is not required.
```

--------------------------------

### FormGenerator#create_application_form

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/FormGenerator.html

Generates a form template file. It uses the `template` method to create a 'form.rb' file in the 'app/forms' directory, structured according to the class path and file name.

```ruby
def create_application_form
  template 'form.rb', File.join('app/forms', class_path, "#{file_name}_form.rb")
end
```

--------------------------------

### YARD Documentation Navigation Logic

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/frames.html

This JavaScript code handles navigation within YARD-generated documentation. It attempts to parse the URL hash for a specific page name, falling back to the main index page if an error occurs or no valid hash is found. It's designed to ensure correct page loading, especially in environments where the hash might be used for deep linking.

```javascript
var mainUrl = 'index.html';
try {
  var match = decodeURIComponent(window.location.hash).match(/^#!(.+)/);
  var name = match ? match[1] : mainUrl;
  var url = new URL(name, location.href);
  window.top.location.replace(url.origin === location.origin ? name : mainUrl);
} catch (e) {
  window.top.location.replace(mainUrl);
}
```

--------------------------------

### HyperActiveForm DSL: proxy_for

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Explains the `proxy_for` method in HyperActiveForm, used to delegate model name and instance variables to the form object. This integration helps Rails' form helpers (like `form_with`) correctly determine URLs and HTTP methods based on the underlying model's state.

```APIDOC
proxy_for(model_class, instance_variable_name)
  - Purpose: Delegates model name and instance variable for Rails form helpers.
  - Arguments:
    - model_class: The class of the underlying model (e.g., User).
    - instance_variable_name: The name of the instance variable holding the model object (e.g., :@user).
  - Behavior:
    - Allows `form_with` or `form_for` to infer URLs and HTTP methods.
    - Enables delegation of certain methods to the underlying object.
  - Example:
    class ProfileForm < ApplicationForm
      proxy_for User, :@user
    end
```

--------------------------------

### Controller Usage for Profile Form

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Shows how to instantiate and handle a HyperActiveForm object within a Rails controller for editing and updating user profiles. It covers initializing the form, submitting parameters, and handling success or failure responses.

```Ruby
class UsersController < ApplicationController

  def edit
    @form = ProfileForm.new(user: current_user)
  end

  def update
    @form = ProfileForm.new(user: current_user)
    if @form.submit(params[:user])
      redirect_to root_path, notice: "Profile updated"
    else
      render :edit, status: :unprocessable_entity
    end
  end
end
```

--------------------------------

### FormGenerator#create_form_test Method

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/TestUnit/Generators/FormGenerator.html

Defines the `create_form_test` instance method for the FormGenerator class. This method generates a form test file using a template, placing it in the 'test/forms' directory structured by the class path and file name.

```Ruby
def create_form_test
  template "form_test.rb", File.join("test/forms", class_path, "#{file_name}_form_test.rb")
end
```

--------------------------------

### Understanding proxy_for in HyperActiveForm

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Explains the `proxy_for` method in HyperActiveForm, detailing how it delegates model name and object instance variables. This is crucial for Rails' `form_for` or `form_with` to correctly determine URLs and HTTP methods based on the form object's associated model.

```APIDOC
proxy_for(model_class, instance_variable_name)
  - Delegates model name and object instance to the specified class and variable.
  - Enables Rails form helpers to infer URLs and HTTP methods.
  - Parameters:
    - model_class: The class of the associated model (e.g., User).
    - instance_variable_name: The name of the instance variable holding the model object (e.g., :@user).
  - Example:
    class ProfileForm < ApplicationForm
      proxy_for User, :@user # Will delegate to @user
    end
  - Note: If URL and method are explicitly passed to form helpers, proxy_for is not required.
```

--------------------------------

### perform Instance Method - HyperActiveForm::Base

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

Placeholder method intended to be overridden by subclasses to define the core logic executed when a form is successfully submitted. This method is called after validations pass.

```Ruby
def perform
  # ... implementation details ...
end
```

--------------------------------

### HyperActiveForm Callbacks (APIDOC)

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Details the callback hooks provided by HyperActiveForm for customizing form behavior. These callbacks allow executing custom code before or after key form operations like attribute assignment and submission.

```APIDOC
HyperActiveForm Callbacks:

HyperActiveForm provides lifecycle callbacks that can be defined within your form classes to hook into specific events.

Available Callbacks:

- `before_submit :method_name`
  - Description: Executes `method_name` before the `submit` or `submit!` method completes.
  - Use Case: Performing pre-submission checks, logging, or modifying data before saving.

- `after_submit :method_name`
  - Description: Executes `method_name` after the `submit` or `submit!` method completes successfully.
  - Use Case: Post-submission actions like sending notifications or redirecting.

- `before_assign_form_attributes :method_name`
  - Description: Executes `method_name` before form attributes are assigned from a hash or object.
  - Use Case: Data sanitization or transformation before attributes are set.

- `after_assign_form_attributes :method_name`
  - Description: Executes `method_name` after form attributes have been assigned.
  - Use Case: Performing actions based on the newly assigned attributes.

Example Usage:

```ruby
class ProfileForm < ApplicationForm
  # ... other form definitions ...

  before_submit :log_submission_attempt
  after_assign_form_attributes :initialize_related_data

  def log_submission_attempt
    Rails.logger.info "Attempting to submit form for user: #{self.user_id}"
  end

  def initialize_related_data
    # Initialize some dependent data based on assigned attributes
    @user = User.find_or_initialize_by(id: self.user_id)
  end
end
```

Related Methods:
- `submit`
- `submit!`
- `assign_form_attributes`
```

--------------------------------

### submit Instance Method - HyperActiveForm::Base

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

Submits the form by assigning attributes from parameters, running validations, and executing the perform method if the form is valid. Returns a boolean indicating success.

```Ruby
def submit(params)
  # ... implementation details ...
end
```

--------------------------------

### HyperActiveForm DSL: perform

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Explains the `perform` method, which is executed after form attributes are assigned and validations pass when using `submit` or `submit!`. This method is the designated place for implementing the core business logic, such as updating or creating records.

```APIDOC
perform
  - Purpose: Executes the core business logic of the form.
  - Trigger: Called by `submit` or `submit!` after attribute assignment and successful validation.
  - Behavior:
    - Implement actions like updating a model (`@user.update!(...)`).
    - If `perform` returns a falsy value, `submit` returns `false` and `submit!` raises `HyperActiveForm::FormDidNotSubmitError`.
    - Raising `HyperActiveForm::CancelForm` within `perform` (or any stage) cancels the submission.
  - Example:
    class ProfileForm < ApplicationForm
      def perform
        @user.update!(first_name: first_name, last_name: last_name, birth_date: birth_date)
      end
    end
```

--------------------------------

### Generate a Form Object with HyperActiveForm

Source: https://github.com/intrepidd/hyperactiveform/blob/main/README.md

Command to generate a new form object and its associated tests using the HyperActiveForm generator.

```bash
$ rails generate form FooBar
```

--------------------------------

### HyperActiveForm Callbacks API

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

HyperActiveForm supports callbacks to execute custom code at specific points during the form submission lifecycle. These include hooks before attribute assignment and before the main submission logic.

```APIDOC
HyperActiveForm Callbacks:

Provides hooks to execute custom logic before or after key form processing steps.

Available Callbacks:

- `before_assign_form_attributes`:
  - Executes immediately before form attributes are assigned from parameters.
  - Can be used for pre-processing or setting up initial state.
  - Example:
    ```ruby
    class ProfileForm < ApplicationForm
      before_assign_form_attributes :prepare_user_data

      def prepare_user_data
        # Logic to run before attributes are assigned
      end
    end
    ```

- `before_submit`:
  - Executes just before the `perform` method is called, after validations pass.
  - Useful for final checks or modifications before the main logic.
  - Example:
    ```ruby
    class ProfileForm < ApplicationForm
      before_submit :validate_related_data

      def validate_related_data
        # Logic to run before the perform method
      end
    end
    ```

- `after_submit`:
  - Executes after the `perform` method has completed successfully.
  - Can be used for post-processing or logging.
  - Example:
    ```ruby
    class ProfileForm < ApplicationForm
      after_submit :log_submission_success

      def log_submission_success
        # Logic to run after the perform method
      end
    end
    ```

Error Handling during Callbacks:
- If a callback raises an exception, the form submission process will halt, and the exception will propagate.
- Raising `HyperActiveForm::CancelForm` within a callback will also cancel the submission, similar to returning `false` from `perform`.
```

--------------------------------

### Generate a New Form Object

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/file.README.html

Command to generate a new form object, including its associated test file, using the Rails generator provided by the HyperActiveForm gem.

```bash
$ rails generate form FooBar
```

--------------------------------

### Rspec::Generators::FormGenerator Methods

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/method_list.html

Documentation for methods within the Rspec::Generators::FormGenerator class, specifically for creating RSpec form specifications.

```APIDOC
#create_form_spec
  Generates an RSpec test specification for a form.
  This method is part of the RSpec generator for forms.
```

--------------------------------

### proxy_for Class Method - HyperActiveForm::Base

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

Delegates ActiveModel methods to a specified object, useful for form helpers like form_for. It takes the class of the object and the object itself as arguments to set up delegation.

```Ruby
def self.proxy_for(klass, object)
  delegate :new_record?, :persisted?, :id, to: object
  singleton_class.delegate :model_name, to: klass
end
```

--------------------------------

### Generate a New Form Object

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

Command to generate a new form object, including its associated test file, using the Rails generator provided by the HyperActiveForm gem.

```bash
$ rails generate form FooBar
```

--------------------------------

### HyperActiveForm Callbacks API

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/index.html

HyperActiveForm supports callbacks to execute custom code at specific points during the form submission lifecycle. These include hooks before attribute assignment and before the main submission logic.

```APIDOC
HyperActiveForm Callbacks:

Provides hooks to execute custom logic before or after key form processing steps.

Available Callbacks:

- `before_assign_form_attributes`:
  - Executes immediately before form attributes are assigned from parameters.
  - Can be used for pre-processing or setting up initial state.
  - Example:
    ```ruby
    class ProfileForm < ApplicationForm
      before_assign_form_attributes :prepare_user_data

      def prepare_user_data
        # Logic to run before attributes are assigned
      end
    end
    ```

- `before_submit`:
  - Executes just before the `perform` method is called, after validations pass.
  - Useful for final checks or modifications before the main logic.
  - Example:
    ```ruby
    class ProfileForm < ApplicationForm
      before_submit :validate_related_data

      def validate_related_data
        # Logic to run before the perform method
      end
    end
    ```

- `after_submit`:
  - Executes after the `perform` method has completed successfully.
  - Can be used for post-processing or logging.
  - Example:
    ```ruby
    class ProfileForm < ApplicationForm
      after_submit :log_submission_success

      def log_submission_success
        # Logic to run after the perform method
      end
    end
    ```

Error Handling during Callbacks:
- If a callback raises an exception, the form submission process will halt, and the exception will propagate.
- Raising `HyperActiveForm::CancelForm` within a callback will also cancel the submission, similar to returning `false` from `perform`.
```

--------------------------------

### submit! Instance Method - HyperActiveForm::Base

Source: https://github.com/intrepidd/hyperactiveform/blob/main/docs/HyperActiveForm/Base.html

Similar to the submit method, but raises a FormDidNotSubmitError if the form is not valid. This provides a more explicit error handling mechanism for invalid submissions.

```Ruby
def submit!(params)
  # ... implementation details ...
end
```