hotwire_nested_form 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 173878e857afa1600895b0db444cb9c60785b587e79599c3bbc7759bc861f587
-  data.tar.gz: 79c140402e129ae87e72525fee18ca125dfe0d2720ea6455c9b88b926996a19a
+  metadata.gz: 7033260639294c3125ab0debe416848833f6b55b04bf9f826ff6686f4d30c6c4
+  data.tar.gz: 6c93778b96b4b2fb757d84f71d1999a559c725528ee5835ed4e6906f1eb77366
 SHA512:
-  metadata.gz: 5eb667ddcbf921baaa2f7b92cd618b40e8bf639fe344c9df3b696c8aee5f81abd9e611ca6c5e1f7cc671a894509ccabfa296584a319e28493bf4e9a22dcc7b30
-  data.tar.gz: c644e0a39ef9e67ff612f0d640617ab22ebfe4fa46a3062178e44d8dad1d6d5d86457ecba53ab5664b965f86e8fd981fb7b19163765026be1eb7b51ec992608a
+  metadata.gz: 12f334f31a6b1e02abb519f1f780618c4749b95673c69fb59d4f65f47af74569d4a3688349d7f3513b4330d83b1caf5ec7e22af15737a04316be09e06c8cbff9
+  data.tar.gz: 981f73f9d25e634be708d81ee3e6e3f08569db17d4c269854b92ca045fbd641f5811294612bc75ea3d2d6b3ca86733862d3e61cb04d31d853acf2be917eae651

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-02-06
+
+### Added
+- Accessibility (a11y) support enabled by default
+  - `data-nested-form-a11y-value` - enable/disable accessibility features (default: `true`)
+  - `role="group"` and `aria-label` automatically set on controller element
+  - Live region (`aria-live="polite"`) for screen reader announcements
+  - Focus management: first input focused after add, add button focused after remove
+  - Announcements: "Item N added.", "Item removed. N remaining.", "Item duplicated."
+- Duplicate/Clone nested items
+  - `link_to_duplicate_association` Ruby helper
+  - `nested-form#duplicate` Stimulus action
+  - Clones item with field values, generates new index, clears persisted record ID
+  - Respects max limit
+  - New events: `nested-form:before-duplicate` (cancelable), `nested-form:after-duplicate`
+
 ## [1.4.0] - 2026-02-06
 
 ### Added

data/Gemfile.lock

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

data/README.md

@@ -389,6 +389,83 @@ 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.
 
+## Accessibility
+
+Accessibility features are **enabled by default**. The controller automatically:
+
+- Sets `role="group"` and `aria-label` on the controller element
+- Creates an `aria-live="polite"` region for screen reader announcements
+- Focuses the first input when a new item is added
+- Moves focus to the "Add" button when an item is removed
+- Announces add/remove/duplicate actions to screen readers
+
+### Disabling Accessibility
+
+```erb
+<div data-controller="nested-form"
+     data-nested-form-a11y-value="false">
+  <!-- fields -->
+</div>
+```
+
+### Custom ARIA Label
+
+Set your own `aria-label` and the controller will preserve it:
+
+```erb
+<div data-controller="nested-form"
+     aria-label="Project tasks">
+  <!-- fields -->
+</div>
+```
+
+## Duplicate/Clone
+
+Duplicate an existing nested item (with its field values) as a starting point for a new item:
+
+### 1. Add Duplicate Button to Partial
+
+```erb
+<%# _task_fields.html.erb %>
+<div class="nested-fields">
+  <%= f.text_field :name %>
+  <%= link_to_duplicate_association "Duplicate", f, class: "btn-sm" %>
+  <%= link_to_remove_association "Remove", f %>
+</div>
+```
+
+### 2. That's It!
+
+Clicking "Duplicate" will:
+- Clone the item with all current field values
+- Generate a new unique index (so Rails creates a new record)
+- Remove the persisted record ID (so it saves as a new record)
+- Respect the max limit
+- Animate the new item if animations are enabled
+- Focus the first input of the clone
+- Announce "Item duplicated." to screen readers
+
+### Duplicate Events
+
+| Event | Cancelable | Detail |
+|-------|------------|--------|
+| `nested-form:before-duplicate` | Yes | `{ source }` |
+| `nested-form:after-duplicate` | No | `{ source, clone }` |
+
+```javascript
+// Customize the clone before it's inserted
+document.addEventListener("nested-form:after-duplicate", (event) => {
+  const clone = event.detail.clone
+  // Clear specific fields in the clone
+  clone.querySelector("input[name*='description']").value = ""
+})
+
+// Prevent duplication conditionally
+document.addEventListener("nested-form:before-duplicate", (event) => {
+  if (someCondition) event.preventDefault()
+})
+```
+
 ## NPM Package (JavaScript-only)
 
 For non-Rails projects using Stimulus, install via npm:
@@ -475,6 +552,31 @@ link_to_remove_association(name, form, options = {}, &block)
 <% end %>
 ```
 
+### link_to_duplicate_association
+
+```ruby
+link_to_duplicate_association(name, form, options = {}, &block)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| (standard HTML options) | | | Passed to the `<a>` tag |
+
+**Examples:**
+
+```erb
+<%# Basic usage %>
+<%= link_to_duplicate_association "Duplicate", f %>
+
+<%# With HTML classes %>
+<%= link_to_duplicate_association "Duplicate", f, class: "btn btn-sm" %>
+
+<%# With block %>
+<%= link_to_duplicate_association f do %>
+  <span class="icon">📋</span> Copy
+<% end %>
+```
+
 ## JavaScript Events
 
 | Event | Cancelable | Detail | When |
@@ -487,6 +589,8 @@ link_to_remove_association(name, form, options = {}, &block)
 | `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 |
+| `nested-form:before-duplicate` | Yes | `{ source }` | Before duplicating item |
+| `nested-form:after-duplicate` | No | `{ source, clone }` | After item duplicated |
 
 **Usage Examples:**
 

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

@@ -10,16 +10,22 @@ export default class extends Controller {
     positionField: { type: String, default: "position" },
     sortHandle: { type: String, default: "" },
     animation: { type: String, default: "" },
-    animationDuration: { type: Number, default: 300 }
+    animationDuration: { type: Number, default: 300 },
+    a11y: { type: Boolean, default: true }
   }
 
   connect() {
+    if (this.a11yValue) this.setupAccessibility()
     this.updateButtonStates()
     if (this.sortableValue) this.initializeSortable()
   }
 
   disconnect() {
     if (this.sortableInstance) this.sortableInstance.destroy()
+    if (this.liveRegion) {
+      this.liveRegion.remove()
+      this.liveRegion = null
+    }
   }
 
   get currentCount() {
@@ -97,6 +103,12 @@ export default class extends Controller {
 
     this.dispatch("after-remove", { detail: { wrapper } })
     this.updateButtonStates()
+
+    if (this.a11yValue) {
+      const addButton = this.element.querySelector('[data-action*="nested-form#add"]')
+      if (addButton) addButton.focus()
+      this.announce(`Item removed. ${this.currentCount} remaining.`)
+    }
   }
 
   getTemplate(trigger) {
@@ -150,6 +162,113 @@ export default class extends Controller {
     if (this.animationValue) {
       this.animateIn(wrapper)
     }
+
+    if (this.a11yValue) {
+      this.focusFirstInput(wrapper)
+      this.announce(`Item ${this.currentCount} added.`)
+    }
+  }
+
+  // Duplicate
+
+  duplicate(event) {
+    event.preventDefault()
+
+    if (this.currentCount >= this.maxValue) {
+      this.dispatch("limit-reached", {
+        detail: { limit: this.maxValue, current: this.currentCount }
+      })
+      return
+    }
+
+    const wrapper = event.currentTarget.closest(`.${this.wrapperClassValue}`)
+    if (!wrapper) return
+
+    const beforeEvent = this.dispatch("before-duplicate", {
+      cancelable: true,
+      detail: { source: wrapper }
+    })
+
+    if (beforeEvent.defaultPrevented) return
+
+    const clone = wrapper.cloneNode(true)
+    const newId = new Date().getTime()
+
+    this.prepareClone(clone, newId)
+
+    wrapper.after(clone)
+
+    this.dispatch("after-duplicate", {
+      detail: { source: wrapper, clone: clone }
+    })
+
+    if (this.animationValue) {
+      this.animateIn(clone)
+    }
+
+    this.updateButtonStates()
+    if (this.sortableValue) this.updatePositions()
+
+    if (this.a11yValue) {
+      this.focusFirstInput(clone)
+      this.announce("Item duplicated.")
+    }
+  }
+
+  prepareClone(clone, newId) {
+    const idInput = clone.querySelector("input[name*='[id]'][type='hidden']")
+    if (idInput) idInput.remove()
+
+    const destroyInput = clone.querySelector("input[name*='_destroy']")
+    if (destroyInput) destroyInput.value = "false"
+
+    const elements = clone.querySelectorAll("input, select, textarea, label")
+    elements.forEach(el => {
+      if (el.name) {
+        el.name = el.name.replace(/\[\d+\]/, `[${newId}]`)
+      }
+      if (el.id) {
+        el.id = el.id.replace(/_\d+_/, `_${newId}_`)
+      }
+      if (el.htmlFor) {
+        el.htmlFor = el.htmlFor.replace(/_\d+_/, `_${newId}_`)
+      }
+    })
+
+    clone.style.display = ""
+  }
+
+  // Accessibility
+
+  setupAccessibility() {
+    this.element.setAttribute("role", "group")
+    if (!this.element.getAttribute("aria-label")) {
+      this.element.setAttribute("aria-label", "Nested form fields")
+    }
+
+    this.liveRegion = document.createElement("div")
+    this.liveRegion.setAttribute("aria-live", "polite")
+    this.liveRegion.setAttribute("aria-atomic", "true")
+    this.liveRegion.classList.add("nested-form-live-region")
+    this.liveRegion.style.cssText = "position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)"
+    this.element.appendChild(this.liveRegion)
+  }
+
+  announce(message) {
+    if (!this.liveRegion) return
+    this.liveRegion.textContent = ""
+    requestAnimationFrame(() => {
+      this.liveRegion.textContent = message
+    })
+  }
+
+  focusFirstInput(wrapper) {
+    const focusable = wrapper.querySelector(
+      'input:not([type="hidden"]), select, textarea'
+    )
+    if (focusable) {
+      setTimeout(() => focusable.focus(), 50)
+    }
   }
 
   // Animations

data/lib/hotwire_nested_form/helpers/duplicate_association.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module HotwireNestedForm
+  module Helpers
+    module DuplicateAssociation
+      # Generates a link to duplicate a nested form item
+      #
+      # @param name [String] Link text (or use block)
+      # @param form [FormBuilder] Nested form object
+      # @param options [Hash] HTML attributes
+      # @yield Block for custom link content
+      # @return [String] HTML link element
+      #
+      # @example Basic usage
+      #   <%= link_to_duplicate_association "Duplicate", f %>
+      #
+      # @example With block
+      #   <%= link_to_duplicate_association f do %>
+      #     <span>Copy</span>
+      #   <% end %>
+      #
+      def link_to_duplicate_association(name = nil, form = nil, options = {}, &)
+        if block_given?
+          options = form || {}
+          form = name
+          name = capture(&)
+        end
+
+        raise ArgumentError, 'form is required' unless form
+
+        options = options.dup
+
+        data = options[:data] || {}
+        data[:action] = 'nested-form#duplicate'
+
+        options[:data] = data
+        options[:href] = '#'
+
+        content_tag(:a, name, options)
+      end
+    end
+  end
+end

data/lib/hotwire_nested_form/helpers.rb

@@ -2,10 +2,12 @@
 
 require_relative 'helpers/add_association'
 require_relative 'helpers/remove_association'
+require_relative 'helpers/duplicate_association'
 
 module HotwireNestedForm
   module Helpers
     include AddAssociation
     include RemoveAssociation
+    include DuplicateAssociation
   end
 end

data/lib/hotwire_nested_form/version.rb

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

data/npm/README.md

@@ -166,6 +166,35 @@ For multi-level nesting, use `<template>` tags and `data-placeholder` attributes
 
 The controller replaces only the matching placeholder per button, so nested templates stay intact.
 
+### Accessibility
+
+Accessibility is **enabled by default**. The controller automatically:
+
+- Sets `role="group"` and `aria-label` on the container
+- Creates a live region for screen reader announcements
+- Manages focus on add/remove/duplicate actions
+
+Disable with:
+
+```html
+<div data-controller="nested-form"
+     data-nested-form-a11y-value="false">
+```
+
+### Duplicate/Clone
+
+Add a duplicate button to clone an existing item with its field values:
+
+```html
+<div class="nested-fields">
+  <input name="items[][name]" value="Task A">
+  <a href="#" data-action="nested-form#duplicate">Duplicate</a>
+  <a href="#" data-action="nested-form#remove">Remove</a>
+</div>
+```
+
+The clone gets a new unique index and any persisted record ID is removed so it saves as a new record.
+
 ### Events
 
 | Event | Cancelable | Detail |
@@ -178,6 +207,8 @@ The controller replaces only the matching placeholder per button, so nested temp
 | `nested-form:minimum-reached` | No | `{ minimum, current }` |
 | `nested-form:before-sort` | Yes | `{ item, oldIndex }` |
 | `nested-form:after-sort` | No | `{ item, oldIndex, newIndex }` |
+| `nested-form:before-duplicate` | Yes | `{ source }` |
+| `nested-form:after-duplicate` | No | `{ source, clone }` |
 
 ### Example: Listen for Events
 

data/npm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotwire-nested-form-stimulus",
-  "version": "1.4.0",
+  "version": "1.5.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",

data/npm/src/nested_form_controller.js

@@ -10,16 +10,22 @@ export default class extends Controller {
     positionField: { type: String, default: "position" },
     sortHandle: { type: String, default: "" },
     animation: { type: String, default: "" },
-    animationDuration: { type: Number, default: 300 }
+    animationDuration: { type: Number, default: 300 },
+    a11y: { type: Boolean, default: true }
   }
 
   connect() {
+    if (this.a11yValue) this.setupAccessibility()
     this.updateButtonStates()
     if (this.sortableValue) this.initializeSortable()
   }
 
   disconnect() {
     if (this.sortableInstance) this.sortableInstance.destroy()
+    if (this.liveRegion) {
+      this.liveRegion.remove()
+      this.liveRegion = null
+    }
   }
 
   get currentCount() {
@@ -97,6 +103,12 @@ export default class extends Controller {
 
     this.dispatch("after-remove", { detail: { wrapper } })
     this.updateButtonStates()
+
+    if (this.a11yValue) {
+      const addButton = this.element.querySelector('[data-action*="nested-form#add"]')
+      if (addButton) addButton.focus()
+      this.announce(`Item removed. ${this.currentCount} remaining.`)
+    }
   }
 
   getTemplate(trigger) {
@@ -150,6 +162,113 @@ export default class extends Controller {
     if (this.animationValue) {
       this.animateIn(wrapper)
     }
+
+    if (this.a11yValue) {
+      this.focusFirstInput(wrapper)
+      this.announce(`Item ${this.currentCount} added.`)
+    }
+  }
+
+  // Duplicate
+
+  duplicate(event) {
+    event.preventDefault()
+
+    if (this.currentCount >= this.maxValue) {
+      this.dispatch("limit-reached", {
+        detail: { limit: this.maxValue, current: this.currentCount }
+      })
+      return
+    }
+
+    const wrapper = event.currentTarget.closest(`.${this.wrapperClassValue}`)
+    if (!wrapper) return
+
+    const beforeEvent = this.dispatch("before-duplicate", {
+      cancelable: true,
+      detail: { source: wrapper }
+    })
+
+    if (beforeEvent.defaultPrevented) return
+
+    const clone = wrapper.cloneNode(true)
+    const newId = new Date().getTime()
+
+    this.prepareClone(clone, newId)
+
+    wrapper.after(clone)
+
+    this.dispatch("after-duplicate", {
+      detail: { source: wrapper, clone: clone }
+    })
+
+    if (this.animationValue) {
+      this.animateIn(clone)
+    }
+
+    this.updateButtonStates()
+    if (this.sortableValue) this.updatePositions()
+
+    if (this.a11yValue) {
+      this.focusFirstInput(clone)
+      this.announce("Item duplicated.")
+    }
+  }
+
+  prepareClone(clone, newId) {
+    const idInput = clone.querySelector("input[name*='[id]'][type='hidden']")
+    if (idInput) idInput.remove()
+
+    const destroyInput = clone.querySelector("input[name*='_destroy']")
+    if (destroyInput) destroyInput.value = "false"
+
+    const elements = clone.querySelectorAll("input, select, textarea, label")
+    elements.forEach(el => {
+      if (el.name) {
+        el.name = el.name.replace(/\[\d+\]/, `[${newId}]`)
+      }
+      if (el.id) {
+        el.id = el.id.replace(/_\d+_/, `_${newId}_`)
+      }
+      if (el.htmlFor) {
+        el.htmlFor = el.htmlFor.replace(/_\d+_/, `_${newId}_`)
+      }
+    })
+
+    clone.style.display = ""
+  }
+
+  // Accessibility
+
+  setupAccessibility() {
+    this.element.setAttribute("role", "group")
+    if (!this.element.getAttribute("aria-label")) {
+      this.element.setAttribute("aria-label", "Nested form fields")
+    }
+
+    this.liveRegion = document.createElement("div")
+    this.liveRegion.setAttribute("aria-live", "polite")
+    this.liveRegion.setAttribute("aria-atomic", "true")
+    this.liveRegion.classList.add("nested-form-live-region")
+    this.liveRegion.style.cssText = "position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)"
+    this.element.appendChild(this.liveRegion)
+  }
+
+  announce(message) {
+    if (!this.liveRegion) return
+    this.liveRegion.textContent = ""
+    requestAnimationFrame(() => {
+      this.liveRegion.textContent = message
+    })
+  }
+
+  focusFirstInput(wrapper) {
+    const focusable = wrapper.querySelector(
+      'input:not([type="hidden"]), select, textarea'
+    )
+    if (focusable) {
+      setTimeout(() => focusable.focus(), 50)
+    }
   }
 
   // Animations

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hotwire_nested_form
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - BhumitBhadani
@@ -52,6 +52,7 @@ files:
 - lib/hotwire_nested_form/form_builder_detector.rb
 - lib/hotwire_nested_form/helpers.rb
 - lib/hotwire_nested_form/helpers/add_association.rb
+- lib/hotwire_nested_form/helpers/duplicate_association.rb
 - lib/hotwire_nested_form/helpers/remove_association.rb
 - lib/hotwire_nested_form/version.rb
 - npm/.npmignore