# Multi-Step Form Wizard

### Overview

The multi-step form wizard allows you to break long forms into manageable steps, improving the user experience by only displaying one step at a time. It's powered by a lightweight Stimulus.js controller and integrates seamlessly with `simple_form` and Tailwind CSS in Lightning Rails.

### Installation & Setup

Follow these steps to implement a form wizard in your Lightning Rails project.

#### 1. Create the Form View

Wrap your form in a `<div data-controller="wizard">` and split it into multiple steps using `data-wizard-target="step"` on each section.

```erb
<div data-controller="wizard" class="space-y-6">
  <%= form_with model: @model, local: true, html: { class: "space-y-4" } do |f| %>
    <!-- Step 1 -->
    <div data-wizard-target="step" class="card bg-base-100 shadow p-6">
      <div class="form-control">
        <%= f.label :first_name, class: "label" %>
        <%= f.text_field :first_name, class: "input input-bordered" %>
      </div>

      <div class="mt-4 flex justify-end">
        <%= button_tag "Next", type: "button",
          data: {
            action: "click->wizard#goToNext",
            next_step: "1"
          },
          class: "btn btn-primary" %>
      </div>
    </div>

    <!-- Step 2 -->
    <div data-wizard-target="step" class="card bg-base-100 shadow p-6 hidden">
      <div class="form-control">
        <%= f.label :last_name, class: "label" %>
        <%= f.text_field :last_name, class: "input input-bordered" %>
      </div>

      <div class="mt-4 flex justify-between">
        <%= button_tag "Previous", type: "button",
          data: {
            action: "click->wizard#goToPrevious",
            previous_step: "1"
          },
          class: "btn btn-outline" %>

        <%= button_tag "Next", type: "button",
          data: {
            action: "click->wizard#goToNext",
            next_step: "2"
          },
          class: "btn btn-primary" %>
      </div>
    </div>

    <!-- Step 3 -->
    <div data-wizard-target="step" class="card bg-base-100 shadow p-6 hidden">
      <div class="form-control">
        <%= f.label :email, class: "label" %>
        <%= f.email_field :email, class: "input input-bordered" %>
      </div>

      <div class="mt-4 flex justify-between">
        <%= button_tag "Previous", type: "button",
          data: {
            action: "click->wizard#goToPrevious",
            previous_step: "2"
          },
          class: "btn btn-outline" %>

        <%= f.submit "Submit", class: "btn btn-success" %>
      </div>
    </div>
  <% end %>
</div>
```

#### 2. Create the Stimulus Controller

Add this Stimulus controller in `app/javascript/controllers/wizard_controller.js`:

```sh
rails g stimulus wizard
```

```js
import { Controller } from '@hotwired/stimulus'

export default class extends Controller {
  static targets = ['step']

  goToNext(event) {
    const nextStep = event.target.dataset.nextStep - 1
    const actualStep = event.target.dataset.nextStep

    this.stepTargets[nextStep].classList.add("hidden")
    this.stepTargets[actualStep].classList.remove("hidden")
  }

  goToPrevious(event) {
    const previousStep = event.target.dataset.previousStep - 1
    const actualStep = event.target.dataset.previousStep

    this.stepTargets[actualStep].classList.add("hidden")
    this.stepTargets[previousStep].classList.remove("hidden")
  }
}
```

Make sure the controllers are registered in `application.js` :

```js
// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
import "@hotwired/turbo-rails"
import "controllers"
```

### Usage

* Each step is wrapped in a `div` with `data-wizard-target="step"`.
* Use `class="hidden"` (Tailwind utility) to hide inactive steps.
* Navigation is handled via `button_tag` with `data-action` for Stimulus event bindings.
* `next_step` and `previous_step` indicate the index of the step to show/hide.

### Best Practices

* Keep each step concise and focused.
* Validate inputs before allowing the user to proceed (add validations or checks in the controller if needed).
* Use consistent styling with Tailwind to provide visual cues for step transitions.

### Troubleshooting

**Issue:** Nothing happens when clicking "Next" or "Previous".\
**Solution:**

* Ensure the Stimulus controller is properly registered and compiled.
* Verify that `data-controller="wizard"` and `data-wizard-target="step"` are correctly placed.
* Make sure the buttons have the correct `data-action`, `next_step`, or `previous_step`.

**Issue:** Steps aren't hiding/showing properly.\
**Solution:**

* Confirm that `class="hidden"` is being toggled correctly.
* Check that `stepTargets` correspond to the order of steps in your HTML.

***

Let me know on Slack if you'd like an enhanced version with progress indicators or form validation!