hotwire_nested_form 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95575593f362dd0db15938a6b130eb2fa7353e12b4c939c84ee4aa1eb00035ec
-  data.tar.gz: 8ace6c3f971faaadc42d2692a6540bd4a907387302963573a904ad7990b1a3b6
+  metadata.gz: 173878e857afa1600895b0db444cb9c60785b587e79599c3bbc7759bc861f587
+  data.tar.gz: 79c140402e129ae87e72525fee18ca125dfe0d2720ea6455c9b88b926996a19a
 SHA512:
-  metadata.gz: 409ccb4b58b6be6caba5a0b8b5634f999337677de6c146ea3bb100bb3bab9496dca69f4ae5c72ed2587419d321552bb4c7bfb09788ac7664069c0fd2e5ae7e0d
-  data.tar.gz: 4b5902764ddc0e1e7b3223cd6f449a325089198a4a0fadee4077638eb7b403bc0179f0105233950c63b73f828339c6b796f577e3d807e67ec66137e286784791
+  metadata.gz: 5eb667ddcbf921baaa2f7b92cd618b40e8bf639fe344c9df3b696c8aee5f81abd9e611ca6c5e1f7cc671a894509ccabfa296584a319e28493bf4e9a22dcc7b30
+  data.tar.gz: c644e0a39ef9e67ff612f0d640617ab22ebfe4fa46a3062178e44d8dad1d6d5d86457ecba53ab5664b965f86e8fd981fb7b19163765026be1eb7b51ec992608a

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-02-06
+
+### Added
+- Add/remove animations with CSS transitions
+  - `data-nested-form-animation-value` - animation type: `"fade"`, `"slide"`, or `""` (none)
+  - `data-nested-form-animation-duration-value` - duration in ms (default: 300)
+  - CSS classes: `nested-form-enter`, `nested-form-enter-active`, `nested-form-exit-active`
+  - Optional animation stylesheet: `hotwire_nested_form/animations.css`
+  - Install with: `rails g hotwire_nested_form:install --animations`
+  - NPM users: `import "hotwire-nested-form-stimulus/css/animations.css"`
+- Deep nesting (multi-level nested forms)
+  - Association-specific placeholders (`NEW_TASK_RECORD`, `NEW_SUBTASK_RECORD`) prevent collisions
+  - Each `link_to_add_association` automatically generates unique placeholders per association
+  - `<template>` tags for template storage (replaces `data-template` attribute for reliable deep nesting)
+  - Full backward compatibility - single-level forms work unchanged
+
+### Changed
+- Template HTML now stored in `<template>` tags instead of `data-template` attributes
+- `link_to_add_association` outputs `<template>` + `<a>` tag pair
+- Controller `remove()` refactored into `remove()` + `removeElement()` for animation support
+- Added `getTemplate()` method for flexible template lookup
+
+## [1.3.0] - 2026-02-06
+
+### Added
+- Drag & drop sorting for nested items (requires SortableJS)
+  - `data-nested-form-sortable-value` - enable sorting
+  - `data-nested-form-position-field-value` - custom position field name
+  - `data-nested-form-sort-handle-value` - CSS selector for drag handle
+- New events: `nested-form:before-sort` and `nested-form:after-sort`
+- CSS classes for drag styling: `nested-form-dragging`, `nested-form-drag-ghost`
+
+### Changed
+- Controller now cleans up Sortable instance on disconnect
+
 ## [1.2.0] - 2026-02-05
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hotwire_nested_form (1.2.0)
+    hotwire_nested_form (1.4.0)
       rails (>= 7.0)
 
 GEM

data/README.md

@@ -180,6 +180,215 @@ document.addEventListener("nested-form:minimum-reached", (event) => {
 })
 ```
 
+## Drag & Drop Sorting
+
+Enable drag & drop reordering with position persistence:
+
+### 1. Install SortableJS
+
+```bash
+# Rails with importmap
+bin/importmap pin sortablejs
+
+# OR npm/yarn
+npm install sortablejs
+```
+
+### 2. Add Position to Your Model
+
+```bash
+rails generate migration AddPositionToTasks position:integer
+rails db:migrate
+```
+
+```ruby
+# app/models/task.rb
+class Task < ApplicationRecord
+  belongs_to :project
+  default_scope { order(:position) }
+end
+```
+
+### 3. Update Your Partial
+
+```erb
+<%# app/views/projects/_task_fields.html.erb %>
+<div class="nested-fields">
+  <%= f.hidden_field :position %>
+  <span class="drag-handle">☰</span>
+  <%= f.text_field :name %>
+  <%= link_to_remove_association "Remove", f %>
+</div>
+```
+
+### 4. Enable Sorting
+
+```erb
+<div data-controller="nested-form"
+     data-nested-form-sortable-value="true"
+     data-nested-form-sort-handle-value=".drag-handle">
+  <!-- nested fields -->
+</div>
+```
+
+### 5. Permit Position in Controller
+
+```ruby
+params.require(:project).permit(:name,
+  tasks_attributes: [:id, :name, :position, :_destroy])
+```
+
+### Sorting Options
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-nested-form-sortable-value` | `false` | Enable drag & drop |
+| `data-nested-form-position-field-value` | `"position"` | Position field name |
+| `data-nested-form-sort-handle-value` | (none) | Drag handle selector |
+
+### Sorting Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `nested-form:before-sort` | `{ item, oldIndex }` | Before drag (cancelable) |
+| `nested-form:after-sort` | `{ item, oldIndex, newIndex }` | After drop |
+
+### Example CSS
+
+```css
+.drag-handle {
+  cursor: grab;
+  user-select: none;
+}
+
+.nested-form-dragging {
+  opacity: 0.8;
+  background: #e3f2fd;
+}
+
+.nested-form-drag-ghost {
+  opacity: 0.4;
+  border: 2px dashed #2196F3;
+}
+```
+
+## Animations
+
+Add smooth CSS transitions when items are added or removed:
+
+```erb
+<div data-controller="nested-form"
+     data-nested-form-animation-value="fade"
+     data-nested-form-animation-duration-value="300">
+  <!-- nested fields -->
+</div>
+```
+
+### Include the Animation Stylesheet
+
+**Rails (generator):**
+```bash
+rails g hotwire_nested_form:install --animations
+```
+
+**Rails (manual):** Add to your stylesheet:
+```css
+@import "hotwire_nested_form/animations";
+```
+
+**NPM:**
+```javascript
+import "hotwire-nested-form-stimulus/css/animations.css"
+```
+
+### Animation Options
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-nested-form-animation-value` | `""` | `"fade"`, `"slide"`, or `""` (none) |
+| `data-nested-form-animation-duration-value` | `300` | Duration in milliseconds |
+
+### CSS Classes
+
+| Class | When Applied |
+|-------|-------------|
+| `nested-form-enter` | Immediately on add |
+| `nested-form-enter-active` | Next frame after add (triggers transition) |
+| `nested-form-exit-active` | On remove (triggers transition, then element is hidden/removed) |
+
+You can customize the animations by overriding these classes in your stylesheet.
+
+## Deep Nesting (Multi-Level)
+
+Nest forms inside forms (e.g. Project -> Tasks -> Subtasks):
+
+### 1. Model Setup
+
+```ruby
+class Project < ApplicationRecord
+  has_many :tasks, dependent: :destroy
+  accepts_nested_attributes_for :tasks, allow_destroy: true
+end
+
+class Task < ApplicationRecord
+  belongs_to :project
+  has_many :subtasks, dependent: :destroy
+  accepts_nested_attributes_for :subtasks, allow_destroy: true
+end
+```
+
+### 2. Form Setup
+
+```erb
+<%# _form.html.erb %>
+<%= form_with model: @project do |f| %>
+  <div data-controller="nested-form">
+    <div id="tasks">
+      <%= f.fields_for :tasks do |tf| %>
+        <%= render "task_fields", f: tf %>
+      <% end %>
+    </div>
+    <%= link_to_add_association "Add Task", f, :tasks,
+          insertion: :append, target: "#tasks" %>
+  </div>
+  <%= f.submit %>
+<% end %>
+
+<%# _task_fields.html.erb %>
+<div class="nested-fields">
+  <%= f.text_field :name %>
+  <%= link_to_remove_association "Remove Task", f %>
+
+  <div data-controller="nested-form">
+    <div id="subtasks">
+      <%= f.fields_for :subtasks do |sf| %>
+        <%= render "subtask_fields", f: sf %>
+      <% end %>
+    </div>
+    <%= link_to_add_association "Add Subtask", f, :subtasks,
+          insertion: :append, target: "#subtasks" %>
+  </div>
+</div>
+
+<%# _subtask_fields.html.erb %>
+<div class="nested-fields">
+  <%= f.text_field :name %>
+  <%= link_to_remove_association "Remove", f %>
+</div>
+```
+
+### 3. Controller Params
+
+```ruby
+def project_params
+  params.require(:project).permit(:name,
+    tasks_attributes: [:id, :name, :_destroy,
+      subtasks_attributes: [:id, :name, :_destroy]])
+end
+```
+
+Each nesting level automatically gets a unique placeholder (`NEW_TASK_RECORD`, `NEW_SUBTASK_RECORD`) so adding items at one level doesn't affect templates at other levels. Each `data-controller="nested-form"` operates independently.
+
 ## NPM Package (JavaScript-only)
 
 For non-Rails projects using Stimulus, install via npm:
@@ -276,6 +485,8 @@ link_to_remove_association(name, form, options = {}, &block)
 | `nested-form:after-remove` | No | `{ wrapper }` | After fields removed |
 | `nested-form:limit-reached` | No | `{ limit, current }` | When max limit reached |
 | `nested-form:minimum-reached` | No | `{ minimum, current }` | When min limit reached |
+| `nested-form:before-sort` | Yes | `{ item, oldIndex }` | Before drag starts |
+| `nested-form:after-sort` | No | `{ item, oldIndex, newIndex }` | After drop completes |
 
 **Usage Examples:**
 

data/app/assets/stylesheets/hotwire_nested_form/animations.css

@@ -0,0 +1,47 @@
+/*
+ * hotwire_nested_form - Animation Styles
+ *
+ * Include this stylesheet for smooth add/remove transitions.
+ * Enable with: data-nested-form-animation-value="fade" or "slide"
+ *
+ * Rails: Include in your application stylesheet or copy to app/assets/stylesheets/
+ * NPM: import "hotwire-nested-form/css/animations.css"
+ */
+
+/* Fade animation (default) */
+.nested-form-enter {
+  opacity: 0;
+  transform: translateY(-10px);
+}
+
+.nested-form-enter-active {
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 300ms ease, transform 300ms ease;
+}
+
+.nested-form-exit-active {
+  opacity: 0;
+  transform: translateY(-10px);
+  transition: opacity 300ms ease, transform 300ms ease;
+}
+
+/* Slide animation */
+.nested-form-enter[data-animation="slide"] {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+}
+
+.nested-form-enter-active[data-animation="slide"] {
+  max-height: 500px;
+  opacity: 1;
+  transition: max-height 300ms ease, opacity 300ms ease;
+}
+
+.nested-form-exit-active[data-animation="slide"] {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+  transition: max-height 300ms ease, opacity 300ms ease;
+}

data/lib/generators/hotwire_nested_form/install_generator.rb

@@ -7,11 +7,21 @@ module HotwireNestedForm
 
       desc 'Install hotwire_nested_form'
 
+      class_option :animations, type: :boolean, default: false,
+                                desc: 'Copy animation stylesheet'
+
       def copy_stimulus_controller
         copy_file 'nested_form_controller.js',
                   'app/javascript/controllers/nested_form_controller.js'
       end
 
+      def copy_animation_stylesheet
+        return unless options[:animations]
+
+        copy_file 'animations.css',
+                  'app/assets/stylesheets/hotwire_nested_form/animations.css'
+      end
+
       def show_post_install_message
         say ''
         say '=' * 60

data/lib/generators/hotwire_nested_form/templates/animations.css

@@ -0,0 +1,47 @@
+/*
+ * hotwire_nested_form - Animation Styles
+ *
+ * Include this stylesheet for smooth add/remove transitions.
+ * Enable with: data-nested-form-animation-value="fade" or "slide"
+ *
+ * Rails: Include in your application stylesheet or copy to app/assets/stylesheets/
+ * NPM: import "hotwire-nested-form/css/animations.css"
+ */
+
+/* Fade animation (default) */
+.nested-form-enter {
+  opacity: 0;
+  transform: translateY(-10px);
+}
+
+.nested-form-enter-active {
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 300ms ease, transform 300ms ease;
+}
+
+.nested-form-exit-active {
+  opacity: 0;
+  transform: translateY(-10px);
+  transition: opacity 300ms ease, transform 300ms ease;
+}
+
+/* Slide animation */
+.nested-form-enter[data-animation="slide"] {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+}
+
+.nested-form-enter-active[data-animation="slide"] {
+  max-height: 500px;
+  opacity: 1;
+  transition: max-height 300ms ease, opacity 300ms ease;
+}
+
+.nested-form-exit-active[data-animation="slide"] {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+  transition: max-height 300ms ease, opacity 300ms ease;
+}

data/lib/generators/hotwire_nested_form/templates/nested_form_controller.js

@@ -5,11 +5,21 @@ export default class extends Controller {
     wrapperClass: { type: String, default: "nested-fields" },
     min: { type: Number, default: 0 },
     max: { type: Number, default: 999999 },
-    limitBehavior: { type: String, default: "disable" }
+    limitBehavior: { type: String, default: "disable" },
+    sortable: { type: Boolean, default: false },
+    positionField: { type: String, default: "position" },
+    sortHandle: { type: String, default: "" },
+    animation: { type: String, default: "" },
+    animationDuration: { type: Number, default: 300 }
   }
 
   connect() {
     this.updateButtonStates()
+    if (this.sortableValue) this.initializeSortable()
+  }
+
+  disconnect() {
+    if (this.sortableInstance) this.sortableInstance.destroy()
   }
 
   get currentCount() {
@@ -34,7 +44,7 @@ export default class extends Controller {
       return
     }
 
-    const template = event.currentTarget.dataset.template
+    const template = this.getTemplate(event.currentTarget)
     const insertion = event.currentTarget.dataset.insertion || "before"
     const targetSelector = event.currentTarget.dataset.target
     const count = parseInt(event.currentTarget.dataset.count) || 1
@@ -45,6 +55,7 @@ export default class extends Controller {
     }
 
     this.updateButtonStates()
+    if (this.sortableValue && !this.sortableInstance) this.initializeSortable()
   }
 
   remove(event) {
@@ -67,6 +78,14 @@ export default class extends Controller {
 
     if (beforeEvent.defaultPrevented) return
 
+    if (this.animationValue) {
+      this.animateOut(wrapper, () => this.removeElement(wrapper))
+    } else {
+      this.removeElement(wrapper)
+    }
+  }
+
+  removeElement(wrapper) {
     const destroyInput = wrapper.querySelector("input[name*='_destroy']")
 
     if (destroyInput) {
@@ -80,9 +99,23 @@ export default class extends Controller {
     this.updateButtonStates()
   }
 
+  getTemplate(trigger) {
+    // Prefer <template> tag (handles deep nesting), fall back to data-template
+    const placeholder = trigger.dataset.placeholder
+    if (placeholder) {
+      const templateEl = this.element.querySelector(
+        `template[data-nested-form-template="${placeholder}"]`
+      )
+      if (templateEl) return templateEl.innerHTML
+    }
+    return trigger.dataset.template
+  }
+
   insertFields(template, insertion, targetSelector, trigger) {
     const newId = new Date().getTime()
-    const content = template.replace(/NEW_RECORD/g, newId)
+    const placeholder = trigger.dataset.placeholder || "NEW_RECORD"
+    const regex = new RegExp(placeholder, "g")
+    const content = template.replace(regex, newId)
 
     const fragment = document.createRange().createContextualFragment(content)
     const wrapper = fragment.firstElementChild
@@ -113,6 +146,37 @@ export default class extends Controller {
     }
 
     this.dispatch("after-add", { detail: { wrapper } })
+
+    if (this.animationValue) {
+      this.animateIn(wrapper)
+    }
+  }
+
+  // Animations
+
+  animateIn(element) {
+    element.classList.add("nested-form-enter")
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        element.classList.add("nested-form-enter-active")
+        setTimeout(() => {
+          element.classList.remove("nested-form-enter", "nested-form-enter-active")
+        }, this.animationDurationValue)
+      })
+    })
+  }
+
+  animateOut(element, callback) {
+    element.classList.add("nested-form-exit-active")
+
+    const done = () => {
+      element.classList.remove("nested-form-exit-active")
+      callback()
+    }
+
+    element.addEventListener("transitionend", done, { once: true })
+    // Fallback if transitionend doesn't fire
+    setTimeout(done, this.animationDurationValue + 50)
   }
 
   updateButtonStates() {
@@ -146,4 +210,79 @@ export default class extends Controller {
         button.style.display = ""
     }
   }
+
+  // Drag & Drop Sorting
+
+  initializeSortable() {
+    if (typeof Sortable === 'undefined') {
+      console.warn('hotwire_nested_form: SortableJS not found. Install it for drag & drop sorting: https://sortablejs.github.io/Sortable/')
+      return
+    }
+
+    const container = this.findSortableContainer()
+    if (!container) return
+
+    this.sortableInstance = Sortable.create(container, {
+      animation: 150,
+      handle: this.sortHandleValue || null,
+      draggable: `.${this.wrapperClassValue}`,
+      ghostClass: 'nested-form-drag-ghost',
+      chosenClass: 'nested-form-dragging',
+      onStart: (evt) => this.onSortStart(evt),
+      onEnd: (evt) => this.onSortEnd(evt)
+    })
+  }
+
+  findSortableContainer() {
+    // Look for common container patterns
+    const selectors = ['#tasks', '#items', '[data-nested-form-target="container"]']
+    for (const selector of selectors) {
+      const container = this.element.querySelector(selector)
+      if (container) return container
+    }
+    // Fallback: find first element containing nested-fields
+    const firstField = this.element.querySelector(`.${this.wrapperClassValue}`)
+    return firstField ? firstField.parentElement : this.element
+  }
+
+  onSortStart(evt) {
+    const beforeEvent = this.dispatch("before-sort", {
+      cancelable: true,
+      detail: { item: evt.item, oldIndex: evt.oldIndex }
+    })
+
+    if (beforeEvent.defaultPrevented) {
+      this.sortableInstance.option("disabled", true)
+      setTimeout(() => this.sortableInstance.option("disabled", false), 0)
+    }
+  }
+
+  onSortEnd(evt) {
+    this.updatePositions()
+
+    this.dispatch("after-sort", {
+      detail: {
+        item: evt.item,
+        oldIndex: evt.oldIndex,
+        newIndex: evt.newIndex
+      }
+    })
+
+    this.updateButtonStates()
+  }
+
+  updatePositions() {
+    const items = this.element.querySelectorAll(
+      `.${this.wrapperClassValue}:not([style*="display: none"])`
+    )
+
+    items.forEach((item, index) => {
+      const positionInput = item.querySelector(
+        `input[name*="[${this.positionFieldValue}]"]`
+      )
+      if (positionInput) {
+        positionInput.value = index + 1
+      }
+    })
+  }
 }

data/lib/hotwire_nested_form/helpers/add_association.rb

@@ -42,32 +42,42 @@ module HotwireNestedForm
         insertion = options.delete(:insertion) || :before
         target = options.delete(:target)
 
+        # Generate association-specific placeholder for deep nesting
+        placeholder = "NEW_#{association.to_s.upcase.singularize}_RECORD"
+
         # Build the template
         template = build_association_template(
           form,
           association,
           partial: partial,
           render_options: render_options,
-          wrap_object: wrap_object
+          wrap_object: wrap_object,
+          placeholder: placeholder
         )
 
-        # Build data attributes
+        # Build data attributes for the link
         data = options[:data] || {}
         data[:action] = 'nested-form#add'
-        data[:template] = template
         data[:insertion] = insertion
         data[:count] = count if count > 1
         data[:target] = target if target
+        data[:placeholder] = placeholder
 
         options[:data] = data
         options[:href] = '#'
 
-        content_tag(:a, name, options)
+        # Use <template> tag to store the HTML template (handles deep nesting)
+        # The template content is generated by Rails' fields_for/render, not user input
+        template_tag = content_tag(:template, template.html_safe, # rubocop:disable Rails/OutputSafety
+                                   data: { nested_form_template: placeholder })
+        link_tag = content_tag(:a, name, options)
+
+        template_tag + link_tag
       end
 
       private
 
-      def build_association_template(form, association, partial:, render_options:, wrap_object:)
+      def build_association_template(form, association, partial:, render_options:, wrap_object:, placeholder:)
         # Get the association reflection
         reflection = form.object.class.reflect_on_association(association)
         raise ArgumentError, "Association #{association} not found" unless reflection
@@ -78,10 +88,8 @@ module HotwireNestedForm
         # Determine partial name
         partial_name = partial || "#{association.to_s.singularize}_fields"
 
-        # Render the fields using fields_for
-        # This works with both standard Rails FormBuilder and SimpleForm::FormBuilder
-        # SimpleForm overrides fields_for to use simple_fields_for internally
-        form.fields_for(association, new_object, child_index: 'NEW_RECORD') do |builder|
+        # Use association-specific placeholder for deep nesting support
+        form.fields_for(association, new_object, child_index: placeholder) do |builder|
           locals = (render_options[:locals] || {}).merge(f: builder)
           render(partial: partial_name, locals: locals)
         end

data/lib/hotwire_nested_form/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HotwireNestedForm
-  VERSION = '1.2.0'
+  VERSION = '1.4.0'
 end

data/npm/README.md

@@ -30,23 +30,33 @@ application.register("nested-form", NestedFormController)
     <!-- Existing nested fields go here -->
   </div>
 
+  <template data-nested-form-template="NEW_ITEM_RECORD">
+    <div class="nested-fields">
+      <input name="items[NEW_ITEM_RECORD][name]">
+      <a href="#" data-action="nested-form#remove">Remove</a>
+    </div>
+  </template>
   <a href="#"
      data-action="nested-form#add"
-     data-template="<div class='nested-fields'><input name='items[][name]'><a href='#' data-action='nested-form#remove'>Remove</a></div>">
+     data-placeholder="NEW_ITEM_RECORD"
+     data-insertion="append"
+     data-target="#items">
     Add Item
   </a>
 </div>
 ```
 
-### Data Attributes
+### Data Attributes (on add button)
 
 | Attribute | Description | Default |
 |-----------|-------------|---------|
-| `data-template` | HTML template for new fields (use `NEW_RECORD` as placeholder) | Required |
+| `data-placeholder` | Placeholder string in template to replace with unique ID | `"NEW_RECORD"` |
 | `data-insertion` | Where to insert: `before`, `after`, `append`, `prepend` | `before` |
 | `data-count` | Number of fields to add per click | `1` |
 | `data-target` | CSS selector for insertion container | Parent element |
 
+**Note:** For backward compatibility, `data-template` (inline HTML) is still supported, but `<template>` tags are recommended for deep nesting support.
+
 ### Min/Max Limits
 
 ```html
@@ -64,6 +74,98 @@ application.register("nested-form", NestedFormController)
 | `data-nested-form-max-value` | Maximum items allowed | unlimited |
 | `data-nested-form-limit-behavior-value` | `"disable"`, `"hide"`, or `"error"` | `"disable"` |
 
+### Drag & Drop Sorting
+
+Requires [SortableJS](https://sortablejs.github.io/Sortable/):
+
+```bash
+npm install sortablejs
+```
+
+```javascript
+import Sortable from 'sortablejs'
+window.Sortable = Sortable
+```
+
+```html
+<div data-controller="nested-form"
+     data-nested-form-sortable-value="true"
+     data-nested-form-sort-handle-value=".drag-handle">
+
+  <div id="items">
+    <div class="nested-fields">
+      <input type="hidden" name="items[][position]" value="1">
+      <span class="drag-handle">☰</span>
+      <!-- other fields -->
+    </div>
+  </div>
+</div>
+```
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-nested-form-sortable-value` | `false` | Enable sorting |
+| `data-nested-form-position-field-value` | `"position"` | Position field name |
+| `data-nested-form-sort-handle-value` | (none) | Drag handle selector |
+
+### Animations
+
+Add smooth CSS transitions when items are added or removed:
+
+```javascript
+import "hotwire-nested-form-stimulus/css/animations.css"
+```
+
+```html
+<div data-controller="nested-form"
+     data-nested-form-animation-value="fade"
+     data-nested-form-animation-duration-value="300">
+  <!-- fields here -->
+</div>
+```
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-nested-form-animation-value` | `""` | `"fade"`, `"slide"`, or `""` (none) |
+| `data-nested-form-animation-duration-value` | `300` | Duration in milliseconds |
+
+### Deep Nesting
+
+For multi-level nesting, use `<template>` tags and `data-placeholder` attributes. Each nesting level needs its own `data-controller="nested-form"` and a unique placeholder:
+
+```html
+<div data-controller="nested-form">
+  <div id="tasks">
+    <!-- task items here -->
+  </div>
+
+  <template data-nested-form-template="NEW_TASK_RECORD">
+    <div class="nested-fields">
+      <input name="items[tasks][NEW_TASK_RECORD][name]">
+
+      <!-- Nested level 2 -->
+      <div data-controller="nested-form">
+        <div id="subtasks"></div>
+        <template data-nested-form-template="NEW_SUBTASK_RECORD">
+          <div class="nested-fields">
+            <input name="items[tasks][NEW_TASK_RECORD][subtasks][NEW_SUBTASK_RECORD][name]">
+            <a href="#" data-action="nested-form#remove">Remove</a>
+          </div>
+        </template>
+        <a href="#" data-action="nested-form#add"
+           data-placeholder="NEW_SUBTASK_RECORD"
+           data-insertion="append" data-target="#subtasks">Add Subtask</a>
+      </div>
+    </div>
+  </template>
+  <a href="#" data-action="nested-form#add"
+     data-placeholder="NEW_TASK_RECORD"
+     data-insertion="append" data-target="#tasks">Add Task</a>
+</div>
+```
+
+The controller replaces only the matching placeholder per button, so nested templates stay intact.
+
 ### Events
 
 | Event | Cancelable | Detail |
@@ -74,6 +176,8 @@ application.register("nested-form", NestedFormController)
 | `nested-form:after-remove` | No | `{ wrapper }` |
 | `nested-form:limit-reached` | No | `{ limit, current }` |
 | `nested-form:minimum-reached` | No | `{ minimum, current }` |
+| `nested-form:before-sort` | Yes | `{ item, oldIndex }` |
+| `nested-form:after-sort` | No | `{ item, oldIndex, newIndex }` |
 
 ### Example: Listen for Events
 

data/npm/css/animations.css

@@ -0,0 +1,46 @@
+/*
+ * hotwire-nested-form - Animation Styles
+ *
+ * Include this stylesheet for smooth add/remove transitions.
+ * Enable with: data-nested-form-animation-value="fade" or "slide"
+ *
+ * Import: import "hotwire-nested-form/css/animations.css"
+ */
+
+/* Fade animation (default) */
+.nested-form-enter {
+  opacity: 0;
+  transform: translateY(-10px);
+}
+
+.nested-form-enter-active {
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 300ms ease, transform 300ms ease;
+}
+
+.nested-form-exit-active {
+  opacity: 0;
+  transform: translateY(-10px);
+  transition: opacity 300ms ease, transform 300ms ease;
+}
+
+/* Slide animation */
+.nested-form-enter[data-animation="slide"] {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+}
+
+.nested-form-enter-active[data-animation="slide"] {
+  max-height: 500px;
+  opacity: 1;
+  transition: max-height 300ms ease, opacity 300ms ease;
+}
+
+.nested-form-exit-active[data-animation="slide"] {
+  max-height: 0;
+  overflow: hidden;
+  opacity: 0;
+  transition: max-height 300ms ease, opacity 300ms ease;
+}

data/npm/package.json

@@ -1,12 +1,13 @@
 {
   "name": "hotwire-nested-form-stimulus",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Stimulus controller for dynamic nested forms - works with Rails, React, Vue, or any Stimulus app",
   "main": "src/index.js",
   "module": "src/index.js",
   "type": "module",
   "files": [
-    "src"
+    "src",
+    "css"
   ],
   "keywords": [
     "stimulus",

data/npm/src/nested_form_controller.js

@@ -5,11 +5,21 @@ export default class extends Controller {
     wrapperClass: { type: String, default: "nested-fields" },
     min: { type: Number, default: 0 },
     max: { type: Number, default: 999999 },
-    limitBehavior: { type: String, default: "disable" }
+    limitBehavior: { type: String, default: "disable" },
+    sortable: { type: Boolean, default: false },
+    positionField: { type: String, default: "position" },
+    sortHandle: { type: String, default: "" },
+    animation: { type: String, default: "" },
+    animationDuration: { type: Number, default: 300 }
   }
 
   connect() {
     this.updateButtonStates()
+    if (this.sortableValue) this.initializeSortable()
+  }
+
+  disconnect() {
+    if (this.sortableInstance) this.sortableInstance.destroy()
   }
 
   get currentCount() {
@@ -34,7 +44,7 @@ export default class extends Controller {
       return
     }
 
-    const template = event.currentTarget.dataset.template
+    const template = this.getTemplate(event.currentTarget)
     const insertion = event.currentTarget.dataset.insertion || "before"
     const targetSelector = event.currentTarget.dataset.target
     const count = parseInt(event.currentTarget.dataset.count) || 1
@@ -45,6 +55,7 @@ export default class extends Controller {
     }
 
     this.updateButtonStates()
+    if (this.sortableValue && !this.sortableInstance) this.initializeSortable()
   }
 
   remove(event) {
@@ -67,6 +78,14 @@ export default class extends Controller {
 
     if (beforeEvent.defaultPrevented) return
 
+    if (this.animationValue) {
+      this.animateOut(wrapper, () => this.removeElement(wrapper))
+    } else {
+      this.removeElement(wrapper)
+    }
+  }
+
+  removeElement(wrapper) {
     const destroyInput = wrapper.querySelector("input[name*='_destroy']")
 
     if (destroyInput) {
@@ -80,9 +99,23 @@ export default class extends Controller {
     this.updateButtonStates()
   }
 
+  getTemplate(trigger) {
+    // Prefer <template> tag (handles deep nesting), fall back to data-template
+    const placeholder = trigger.dataset.placeholder
+    if (placeholder) {
+      const templateEl = this.element.querySelector(
+        `template[data-nested-form-template="${placeholder}"]`
+      )
+      if (templateEl) return templateEl.innerHTML
+    }
+    return trigger.dataset.template
+  }
+
   insertFields(template, insertion, targetSelector, trigger) {
     const newId = new Date().getTime()
-    const content = template.replace(/NEW_RECORD/g, newId)
+    const placeholder = trigger.dataset.placeholder || "NEW_RECORD"
+    const regex = new RegExp(placeholder, "g")
+    const content = template.replace(regex, newId)
 
     const fragment = document.createRange().createContextualFragment(content)
     const wrapper = fragment.firstElementChild
@@ -113,6 +146,37 @@ export default class extends Controller {
     }
 
     this.dispatch("after-add", { detail: { wrapper } })
+
+    if (this.animationValue) {
+      this.animateIn(wrapper)
+    }
+  }
+
+  // Animations
+
+  animateIn(element) {
+    element.classList.add("nested-form-enter")
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        element.classList.add("nested-form-enter-active")
+        setTimeout(() => {
+          element.classList.remove("nested-form-enter", "nested-form-enter-active")
+        }, this.animationDurationValue)
+      })
+    })
+  }
+
+  animateOut(element, callback) {
+    element.classList.add("nested-form-exit-active")
+
+    const done = () => {
+      element.classList.remove("nested-form-exit-active")
+      callback()
+    }
+
+    element.addEventListener("transitionend", done, { once: true })
+    // Fallback if transitionend doesn't fire
+    setTimeout(done, this.animationDurationValue + 50)
   }
 
   updateButtonStates() {
@@ -146,4 +210,79 @@ export default class extends Controller {
         button.style.display = ""
     }
   }
+
+  // Drag & Drop Sorting
+
+  initializeSortable() {
+    if (typeof Sortable === 'undefined') {
+      console.warn('hotwire_nested_form: SortableJS not found. Install it for drag & drop sorting: https://sortablejs.github.io/Sortable/')
+      return
+    }
+
+    const container = this.findSortableContainer()
+    if (!container) return
+
+    this.sortableInstance = Sortable.create(container, {
+      animation: 150,
+      handle: this.sortHandleValue || null,
+      draggable: `.${this.wrapperClassValue}`,
+      ghostClass: 'nested-form-drag-ghost',
+      chosenClass: 'nested-form-dragging',
+      onStart: (evt) => this.onSortStart(evt),
+      onEnd: (evt) => this.onSortEnd(evt)
+    })
+  }
+
+  findSortableContainer() {
+    // Look for common container patterns
+    const selectors = ['#tasks', '#items', '[data-nested-form-target="container"]']
+    for (const selector of selectors) {
+      const container = this.element.querySelector(selector)
+      if (container) return container
+    }
+    // Fallback: find first element containing nested-fields
+    const firstField = this.element.querySelector(`.${this.wrapperClassValue}`)
+    return firstField ? firstField.parentElement : this.element
+  }
+
+  onSortStart(evt) {
+    const beforeEvent = this.dispatch("before-sort", {
+      cancelable: true,
+      detail: { item: evt.item, oldIndex: evt.oldIndex }
+    })
+
+    if (beforeEvent.defaultPrevented) {
+      this.sortableInstance.option("disabled", true)
+      setTimeout(() => this.sortableInstance.option("disabled", false), 0)
+    }
+  }
+
+  onSortEnd(evt) {
+    this.updatePositions()
+
+    this.dispatch("after-sort", {
+      detail: {
+        item: evt.item,
+        oldIndex: evt.oldIndex,
+        newIndex: evt.newIndex
+      }
+    })
+
+    this.updateButtonStates()
+  }
+
+  updatePositions() {
+    const items = this.element.querySelectorAll(
+      `.${this.wrapperClassValue}:not([style*="display: none"])`
+    )
+
+    items.forEach((item, index) => {
+      const positionInput = item.querySelector(
+        `input[name*="[${this.positionFieldValue}]"]`
+      )
+      if (positionInput) {
+        positionInput.value = index + 1
+      }
+    })
+  }
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_nested_form
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - BhumitBhadani
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 2026-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -40,10 +40,12 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- app/assets/stylesheets/hotwire_nested_form/animations.css
 - gemfiles/rails_7.0.gemfile
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_8.0.gemfile
 - lib/generators/hotwire_nested_form/install_generator.rb
+- lib/generators/hotwire_nested_form/templates/animations.css
 - lib/generators/hotwire_nested_form/templates/nested_form_controller.js
 - lib/hotwire_nested_form.rb
 - lib/hotwire_nested_form/engine.rb
@@ -54,6 +56,7 @@ files:
 - lib/hotwire_nested_form/version.rb
 - npm/.npmignore
 - npm/README.md
+- npm/css/animations.css
 - npm/package.json
 - npm/src/index.js
 - npm/src/nested_form_controller.js