feature #60902 [TwigBridgeRessources] add aria-invalid and aria-describedby on form inputs when validation failure exist (jeanfrancois-morin)

fabpot · fabpot · commit 871b5b2674b8 · 2025-09-24T09:02:47.000+02:00
This PR was squashed before being merged into the 7.4 branch. Discussion ---------- [TwigBridgeRessources] add aria-invalid and aria-describedby on form inputs when validation failure exist | Q | A | ------------- | --- | Branch? | 7.4 | Bug fix? | no | New feature? | yes | Deprecations? | no | Issues | | License | MIT ## Context and objective This PR aims to add the appropriate ARIA attributes (`aria-invalid` and `aria-describedby`) to form fields when validation errors are present. The proposal is based on the recommendations of [WCAG 2.1](https://www.w3.org/TR/WCAG21/#error-identification) and specifically the technique [ARIA21](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA21), which describes the combined use of `aria-invalid="true"` and `aria-describedby="<TEXT_ERROR_ID>"` AFTER user input validation. It seems particularly relevant to implement this since SymfonyUX's LiveComponent allows for an auto-validation system, enabling real-time error feedback to users as they fill out the form. Concretely, users of screen readers will be informed of the presence of errors as soon as they focus on the form field, and if an explicit error message is associated, they can access it immediately. Note that the `aria-describedby` attribute can point to one or more HTML elements, allowing multiple messages (for example, a help message and an error message) to be vocalized. This PR takes this possibility into account by associating each field with the text passages `_field_id_help_` and `_field_id_errors_` when applicable. ## Twig Side The proposal is integrated into all form themes through the main template `form_div_layout.html.twig`, except for the files `bootstrap_4_layout.html.twig` and `bootstrap_4_horizontal_layout.html.twig`. In these files, errors were initially placed inside the associated label, so it is not necessary to add the `aria-describedby` attribute. Errors will be vocalized automatically and immediately after the label content. The `aria-invalid="true"` attribute remains necessary to indicate the presence of errors. Let me know if this approach works for you, or if you would like me to modify any aspects. Commits ------- 6957eba [TwigBridgeRessources] add aria-invalid and aria-describedby on form inputs when validation failure exist
diff --git a/src/Symfony/Bridge/Twig/CHANGELOG.md b/src/Symfony/Bridge/Twig/CHANGELOG.md
@@ -6,6 +6,7 @@ CHANGELOG
 
  * Add `access_decision()` and `access_decision_for_user()` Twig functions
  * Call `form_label_content` inside `button_widget` block to render button label
+ * Add `aria-invalid` and `aria-describedby` attributes to form fields when validation errors are present
 
 7.3
 ---
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig
@@ -22,11 +22,7 @@ col-sm-2
 
 {# Rows #}
 
-{% block form_row -%}
-    {%- set widget_attr = {} -%}
-    {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
-    {%- endif -%}
+{% block form_row_render -%}
     <div{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' form-group' ~ ((not compound or force_error|default(false)) and not valid ? ' has-error'))|trim})} %}{{ block('attributes') }}{% endwith %}>
         {{- form_label(form) -}}
         <div class="{{ block('form_group_class') }}">
@@ -35,7 +31,7 @@ col-sm-2
             {{- form_errors(form) -}}
         </div>
 {##}</div>
-{%- endblock form_row %}
+{%- endblock form_row_render -%}
 
 {% block submit_row -%}
     <div{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' form-group')|trim})} %}{{ block('attributes') }}{% endwith %}>{#--#}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig
@@ -127,18 +127,14 @@
 
 {# Rows #}
 
-{% block form_row -%}
-    {%- set widget_attr = {} -%}
-    {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
-    {%- endif -%}
+{% block form_row_render -%}
     <div{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' form-group' ~ ((not compound or force_error|default(false)) and not valid ? ' has-error'))|trim})} %}{{ block('attributes') }}{% endwith %}>
         {{- form_label(form) }} {# -#}
         {{ form_widget(form, widget_attr) }} {# -#}
         {{- form_help(form) -}}
         {{ form_errors(form) }} {# -#}
     </div> {# -#}
-{%- endblock form_row %}
+{%- endblock form_row_render -%}
 
 {% block button_row -%}
     <div{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' form-group')|trim})} %}{{ block('attributes') }}{% endwith %}>
@@ -189,7 +185,7 @@
     {% if form is not rootform %}<span class="help-block">{% else %}<div class="alert alert-danger">{% endif %}
     <ul class="list-unstyled">
         {%- for error in errors -%}
-            <li><span class="glyphicon glyphicon-exclamation-sign"></span> {{ error.message }}</li>
+            <li id="{{ id ~ '_error' ~ loop.index }}"><span class="glyphicon glyphicon-exclamation-sign"></span> {{ error.message }}</li>
         {%- endfor -%}
     </ul>
     {% if form is not rootform %}</span>{% else %}</div>{% endif %}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig
@@ -24,10 +24,14 @@ col-sm-2
     {%- if expanded is defined and expanded -%}
         {{ block('fieldset_form_row') }}
     {%- else -%}
-    {%- set widget_attr = {} -%}
+    {%- set attr = {} -%}
     {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
+        {%- set attr = attr|merge({'aria-describedby': id ~ '_help'}) -%}
+    {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set attr = attr|merge({'aria-invalid': 'true'}) -%}
     {%- endif -%}
+    {%- set widget_attr = {attr: attr} -%}
         <div{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' form-group row' ~ ((not compound or force_error|default(false)) and not valid ? ' is-invalid'))|trim})} %}{{ block('attributes') }}{% endwith %}>
             {{- form_label(form) -}}
             <div class="{{ block('form_group_class') }}">
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_layout.html.twig
@@ -282,10 +282,14 @@
     {%- if compound is defined and compound -%}
         {%- set element = 'fieldset' -%}
     {%- endif -%}
-    {%- set widget_attr = {} -%}
+    {%- set attr = {} -%}
     {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
+        {%- set attr = attr|merge({'aria-describedby': id ~ '_help'}) -%}
     {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set attr = attr|merge({'aria-invalid': 'true'}) -%}
+    {%- endif -%}
+    {%- set widget_attr = {attr: attr} -%}
     <{{ element|default('div') }}{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' form-group')|trim})} %}{{ block('attributes') }}{% endwith %}>
         {{- form_label(form) -}}
         {{- form_widget(form, widget_attr) -}}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_horizontal_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_horizontal_layout.html.twig
@@ -23,14 +23,10 @@
 
 {# Rows #}
 
-{% block form_row -%}
+{% block form_row_render -%}
     {%- if expanded is defined and expanded -%}
         {{ block('fieldset_form_row') }}
     {%- else -%}
-        {%- set widget_attr = {} -%}
-        {%- if help -%}
-            {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
-        {%- endif -%}
         {%- set row_class = row_class|default(row_attr.class|default('mb-3')) -%}
         {%- set is_form_floating = is_form_floating|default('form-floating' in row_class) -%}
         {%- set is_input_group = is_input_group|default('input-group' in row_class) -%}
@@ -68,7 +64,7 @@
             {%- endif -%}
         {##}</div>
     {%- endif -%}
-{%- endblock form_row %}
+{%- endblock form_row_render %}
 
 {% block fieldset_form_row -%}
     {%- set widget_attr = {} -%}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_5_layout.html.twig
@@ -320,14 +320,10 @@
 
 {# Rows #}
 
-{%- block form_row -%}
+{%- block form_row_render -%}
     {%- if compound is defined and compound -%}
         {%- set element = 'fieldset' -%}
     {%- endif -%}
-    {%- set widget_attr = {} -%}
-    {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
-    {%- endif -%}
     {%- set row_class = row_class|default(row_attr.class|default('mb-3')|trim) -%}
     <{{ element|default('div') }}{% with {attr: row_attr|merge({class: row_class})} %}{{ block('attributes') }}{% endwith %}>
         {%- if 'form-floating' in row_class -%}
@@ -340,7 +336,7 @@
         {{- form_help(form) -}}
         {{- form_errors(form) -}}
     </{{ element|default('div') }}>
-{%- endblock form_row %}
+{%- endblock form_row_render %}
 
 {%- block button_row -%}
     <div{% with {attr: row_attr|merge({class: row_attr.class|default('mb-3')|trim})} %}{{ block('attributes') }}{% endwith %}>
@@ -353,7 +349,7 @@
 {%- block form_errors -%}
     {%- if errors|length > 0 -%}
         {%- for error in errors -%}
-            <div class="{% if form is not rootform %}invalid-feedback{% else %}alert alert-danger{% endif %} d-block">{{ error.message }}</div>
+            <div class="{% if form is not rootform %}invalid-feedback{% else %}alert alert-danger{% endif %} d-block" id="{{ id ~ '_error' ~ loop.index }}">{{ error.message }}</div>
         {%- endfor -%}
     {%- endif %}
 {%- endblock form_errors %}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
@@ -344,17 +344,32 @@
 {%- endblock repeated_row -%}
 
 {%- block form_row -%}
-    {%- set widget_attr = {} -%}
+    {%- set attr = {} -%}
+    {%- set aria_describedby = [] -%}
     {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
+        {%- set aria_describedby = aria_describedby|merge([id ~ '_help']) -%}
     {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set aria_describedby = aria_describedby|merge(errors|map((_, index) => id ~ '_error' ~ (index + 1))) -%}
+    {%- endif -%}
+    {%- if aria_describedby|length > 0 -%}
+        {%- set attr = attr|merge({'aria-describedby': aria_describedby|join(' ')}) -%}
+    {%- endif -%}
+    {%- if errors|length > 0 -%}
+        {%- set attr = attr|merge({'aria-invalid': 'true'}) -%}
+    {%- endif -%}
+    {%- set widget_attr = {attr: attr} -%}
+    {{- block('form_row_render') -}}
+{%- endblock form_row -%}
+
+{%- block form_row_render -%}
     <div{% with {attr: row_attr} %}{{ block('attributes') }}{% endwith %}>
         {{- form_label(form) -}}
         {{- form_errors(form) -}}
         {{- form_widget(form, widget_attr) -}}
         {{- form_help(form) -}}
     </div>
-{%- endblock form_row -%}
+{%- endblock form_row_render -%}
 
 {%- block button_row -%}
     <div{% with {attr: row_attr} %}{{ block('attributes') }}{% endwith %}>
@@ -399,7 +414,7 @@
     {%- if errors|length > 0 -%}
     <ul>
         {%- for error in errors -%}
-            <li>{{ error.message }}</li>
+            <li id="{{ id ~ '_error' ~ loop.index }}">{{ error.message }}</li>
         {%- endfor -%}
     </ul>
     {%- endif -%}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig
@@ -1,10 +1,6 @@
 {% use 'form_div_layout.html.twig' %}
 
-{%- block form_row -%}
-    {%- set widget_attr = {} -%}
-    {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
-    {%- endif -%}
+{%- block form_row_render -%}
     <tr{% with {attr: row_attr} %}{{ block('attributes') }}{% endwith %}>
         <td>
             {{- form_label(form) -}}
@@ -15,7 +11,7 @@
             {{- form_help(form) -}}
         </td>
     </tr>
-{%- endblock form_row -%}
+{%- endblock form_row_render -%}
 
 {%- block button_row -%}
     <tr{% with {attr: row_attr} %}{{ block('attributes') }}{% endwith %}>
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/foundation_5_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/foundation_5_layout.html.twig
@@ -281,11 +281,7 @@
 
 {# Rows #}
 
-{% block form_row -%}
-    {%- set widget_attr = {} -%}
-    {%- if help -%}
-        {%- set widget_attr = {attr: {'aria-describedby': id ~ '_help'}} -%}
-    {%- endif -%}
+{% block form_row_render -%}
     <div{% with {attr: row_attr|merge({class: (row_attr.class|default('') ~ ' row')|trim})} %}{{ block('attributes') }}{% endwith %}>
         <div class="large-12 columns{% if (not compound or force_error|default(false)) and not valid %} error{% endif %}">
             {{- form_label(form) -}}
@@ -294,7 +290,7 @@
             {{- form_errors(form) -}}
         </div>
     </div>
-{%- endblock form_row %}
+{%- endblock form_row_render %}
 
 {% block choice_row -%}
     {% set force_error = true %}
@@ -342,8 +338,7 @@
     {% if errors|length > 0 -%}
         {% if form is not rootform %}<small class="error">{% else %}<div data-alert class="alert-box alert">{% endif %}
         {%- for error in errors -%}
-            {{ error.message }}
-            {% if not loop.last %}, {% endif %}
+            <span id="{{ id ~ '_error' ~ loop.index }}">{{ error.message }}</span>{% if not loop.last %}, {% endif %}
         {%- endfor -%}
         {% if form is not rootform %}</small>{% else %}</div>{% endif %}
     {%- endif %}
diff --git a/src/Symfony/Bridge/Twig/Resources/views/Form/tailwind_2_layout.html.twig b/src/Symfony/Bridge/Twig/Resources/views/Form/tailwind_2_layout.html.twig
@@ -24,7 +24,7 @@
     {%- if errors|length > 0 -%}
         <ul>
             {%- for error in errors -%}
-                <li class="{{ error_item_class|default('text-red-700') }}">{{ error.message }}</li>
+                <li class="{{ error_item_class|default('text-red-700') }}" id="{{ id ~ '_error' ~ loop.index }}">{{ error.message }}</li>
             {%- endfor -%}
         </ul>
     {%- endif -%}
