Fixed #32819 -- Established relationship between form fields and their help text.

Thanks Nimra for the initial patch.

Thanks Natalia Bidart, Thibaud Colas, David Smith, and Mariusz Felisiak
for reviews.

3 files changed, 58 insertions, 4 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index e443e9eabf..77ccc9e862 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -275,6 +275,48 @@ fields. We've specified ``auto_id=False`` to simplify the output:
     <div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>
     <div>Cc myself:<input type="checkbox" name="cc_myself"></div>
 
+When a field has help text and :attr:`~django.forms.BoundField.id_for_label`
+returns a value, we associate ``help_text`` with the input using the
+``aria-describedby`` HTML attribute:
+
+.. code-block:: pycon
+
+    >>> from django import forms
+    >>> class UserForm(forms.Form):
+    ...     username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
+    ...
+    >>> f = UserForm()
+    >>> print(f)
+    <div>
+    <label for="id_username">Username:</label>
+    <div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
+    <input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
+    </div>
+
+When adding a custom ``aria-describedby`` attribute, make sure to also include
+the ``id`` of the ``help_text`` element (if used) in the desired order. For
+screen reader users, descriptions will be read in their order of appearance
+inside ``aria-describedby``:
+
+.. code-block:: pycon
+
+    >>> class UserForm(forms.Form):
+    ...     username = forms.CharField(
+    ...         max_length=255,
+    ...         help_text="e.g., user@example.com",
+    ...         widget=forms.TextInput(
+    ...             attrs={"aria-describedby": "custom-description id_username_helptext"},
+    ...         ),
+    ...     )
+    ...
+    >>> f = UserForm()
+    >>> print(f["username"])
+    <input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>
+
+.. versionchanged:: 5.0
+
+    ``aria-describedby`` was added to associate ``help_text`` with its input.
+
 ``error_messages``
 ------------------
 
diff --git a/docs/releases/5.0.txt b/docs/releases/5.0.txt
index a2a04c6060..f309721d44 100644
--- a/docs/releases/5.0.txt
+++ b/docs/releases/5.0.txt
@@ -61,7 +61,9 @@ For example, the template below:
     <div>
       {{ form.name.label_tag }}
       {% if form.name.help_text %}
-        <div class="helptext">{{ form.name.help_text|safe }}</div>
+        <div class="helptext" id="{{ form.name.id_for_label }}_helptext">
+          {{ form.name.help_text|safe }}
+        </div>
       {% endif %}
       {{ form.name.errors }}
       {{ form.name }}
@@ -69,7 +71,9 @@ For example, the template below:
         <div class="col">
           {{ form.email.label_tag }}
           {% if form.email.help_text %}
-            <div class="helptext">{{ form.email.help_text|safe }}</div>
+            <div class="helptext" id="{{ form.email.id_for_label }}_helptext">
+              {{ form.email.help_text|safe }}
+            </div>
           {% endif %}
           {{ form.email.errors }}
           {{ form.email }}
@@ -77,7 +81,9 @@ For example, the template below:
         <div class="col">
           {{ form.password.label_tag }}
           {% if form.password.help_text %}
-            <div class="helptext">{{ form.password.help_text|safe }}</div>
+            <div class="helptext" id="{{ form.password.id_for_label }}_helptext">
+              {{ form.password.help_text|safe }}
+            </div>
           {% endif %}
           {{ form.password.errors }}
           {{ form.password }}
@@ -294,6 +300,10 @@ Forms
 * The new ``assume_scheme`` argument for :class:`~django.forms.URLField` allows
   specifying a default URL scheme.
 
+* In order to improve accessibility and enable screen readers to associate form
+  fields with their help text, the form field now includes the
+  ``aria-describedby`` HTML attribute.
+
 Generic Views
 ~~~~~~~~~~~~~
 
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index 27ea496ca6..673111b025 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -723,7 +723,9 @@ loop:
             {{ field.errors }}
             {{ field.label_tag }} {{ field }}
             {% if field.help_text %}
-            <p class="help">{{ field.help_text|safe }}</p>
+              <p class="help" id="{{ field.id_for_label }}_helptext">
+                {{ field.help_text|safe }}
+              </p>
             {% endif %}
         </div>
     {% endfor %}