From 4bb326fee57aaa19f7c936f3222ed1edeeac9068 Mon Sep 17 00:00:00 2001
From: Guillem Arias Fauste <accounts@gariasf.com>
Date: Sat, 23 May 2026 08:53:56 +0200
Subject: [PATCH] docs(ds-toggle): warn against external hidden_field_tag with
 same name (#1925)

DS::Toggle already renders a paired hidden field for the off-state
value. Adding an external `hidden_field_tag` with the same `name` in a
caller view causes ID/label collisions (the auto-generated id matches
the checkbox id, so `<label for=...>` targets the hidden field) and
sends duplicate params.

Inline ERB comment so the warning surfaces wherever the component is
read or copied.
---
 app/components/DS/toggle.html.erb | 1 +
 1 file changed, 1 insertion(+)

diff --git a/app/components/DS/toggle.html.erb b/app/components/DS/toggle.html.erb
index 5b9fe94de..327a995b4 100644
--- a/app/components/DS/toggle.html.erb
+++ b/app/components/DS/toggle.html.erb
@@ -1,4 +1,5 @@
 <div class="relative inline-block select-none">
+  <%# Paired hidden field carries the off-state value when the checkbox is unchecked. Do NOT add an external `hidden_field_tag` with the same `name` in the caller view — it causes ID/label collisions and duplicate params. %>
   <%= hidden_field_tag name, unchecked_value, id: nil %>
   <%# `role="switch"` upgrades the underlying checkbox so AT users hear
       "switch, on" / "switch, off" instead of "checkbox, checked". The