Merge pull request #727 from NHSDigital/DTOSS-11446-visually-hidden-label-text

MatMoore · web-flow · commit 6c1c4e0a9095 · 2025-11-17T13:41:54.000Z
Allow modified labels for screenreaders and assistive tech
diff --git a/manage_breast_screening/mammograms/forms/symptom_forms.py b/manage_breast_screening/mammograms/forms/symptom_forms.py
@@ -233,13 +233,15 @@ def create(self, appointment, request):
 class LumpForm(SymptomForm):
     area = CommonFields.area_radios(symptom_name="lump")
     area_description_right_breast = CommonFields.area_description(
-        "lump", visually_hidden_label_suffix="right breast"
+        "lump", visually_hidden_label_suffix=": right breast"
     )
     area_description_left_breast = CommonFields.area_description(
-        "lump", visually_hidden_label_suffix="left breast"
+        "lump", visually_hidden_label_suffix=": left breast"
     )
     area_description_other = CommonFields.area_description(
-        "lump", visually_hidden_label_suffix="other", classes="nhsuk-u-width-two-thirds"
+        "lump",
+        visually_hidden_label_suffix=": other",
+        classes="nhsuk-u-width-two-thirds",
     )
     when_started = CommonFields.when_started
     specific_date = CommonFields.specific_date
@@ -269,14 +271,14 @@ def __init__(self, instance=None, **kwargs):
 class SwellingOrShapeChangeForm(SymptomForm):
     area = CommonFields.area_radios(symptom_name="swelling or shape change")
     area_description_right_breast = CommonFields.area_description(
-        "swelling or shape change", visually_hidden_label_suffix="right breast"
+        "swelling or shape change", visually_hidden_label_suffix=": right breast"
     )
     area_description_left_breast = CommonFields.area_description(
-        "swelling or shape change", visually_hidden_label_suffix="left breast"
+        "swelling or shape change", visually_hidden_label_suffix=": left breast"
     )
     area_description_other = CommonFields.area_description(
         "swelling or shape change",
-        visually_hidden_label_suffix="other",
+        visually_hidden_label_suffix=": other",
         classes="nhsuk-u-width-two-thirds",
     )
     when_started = CommonFields.when_started
@@ -311,14 +313,14 @@ def __init__(self, instance=None, **kwargs):
 class SkinChangeForm(SymptomForm):
     area = CommonFields.area_radios(symptom_name="skin change")
     area_description_right_breast = CommonFields.area_description(
-        "skin change", visually_hidden_label_suffix="right breast"
+        "skin change", visually_hidden_label_suffix=": right breast"
     )
     area_description_left_breast = CommonFields.area_description(
-        "skin change", visually_hidden_label_suffix="left breast"
+        "skin change", visually_hidden_label_suffix=": left breast"
     )
     area_description_other = CommonFields.area_description(
         "skin change",
-        visually_hidden_label_suffix="other",
+        visually_hidden_label_suffix=": other",
         classes="nhsuk-u-width-two-thirds",
     )
     symptom_sub_type = ChoiceField(
@@ -442,13 +444,13 @@ def area_initial(self, area):
 class OtherSymptomForm(SymptomForm):
     area = CommonFields.area_radios()
     area_description_right_breast = CommonFields.area_description(
-        visually_hidden_label_suffix="right breast"
+        visually_hidden_label_suffix=": right breast"
     )
     area_description_left_breast = CommonFields.area_description(
-        visually_hidden_label_suffix="left breast"
+        visually_hidden_label_suffix=": left breast"
     )
     area_description_other = CommonFields.area_description(
-        visually_hidden_label_suffix="other", classes="nhsuk-u-width-two-thirds"
+        visually_hidden_label_suffix=": other", classes="nhsuk-u-width-two-thirds"
     )
     symptom_sub_type_details = CharField(
         label="Describe the symptom",
diff --git a/manage_breast_screening/nhsuk_forms/fields/boolean_field.py b/manage_breast_screening/nhsuk_forms/fields/boolean_field.py
@@ -11,6 +11,8 @@ def __init__(
         *args,
         hint=None,
         label_classes=None,
+        visually_hidden_label_prefix=None,
+        visually_hidden_label_suffix=None,
         classes=None,
         **kwargs,
     ):
@@ -19,5 +21,7 @@ def __init__(
         self.hint = hint
         self.classes = classes
         self.label_classes = label_classes
+        self.visually_hidden_label_prefix = visually_hidden_label_prefix
+        self.visually_hidden_label_suffix = visually_hidden_label_suffix
 
         super().__init__(*args, **kwargs)
diff --git a/manage_breast_screening/nhsuk_forms/fields/char_field.py b/manage_breast_screening/nhsuk_forms/fields/char_field.py
@@ -22,13 +22,15 @@ def __init__(
         hint=None,
         label_classes=None,
         classes=None,
+        visually_hidden_label_prefix=None,
         visually_hidden_label_suffix=None,
         inputmode=None,
         **kwargs,
     ):
         self.hint = hint
         self.classes = classes
         self.label_classes = label_classes
+        self.visually_hidden_label_prefix = visually_hidden_label_prefix
         self.visually_hidden_label_suffix = visually_hidden_label_suffix
         self.max_length = max_length
         self.max_words = max_words
diff --git a/manage_breast_screening/nhsuk_forms/fields/choice_fields.py b/manage_breast_screening/nhsuk_forms/fields/choice_fields.py
@@ -58,6 +58,8 @@ def __init__(
         *args,
         hint=None,
         label_classes="nhsuk-fieldset__legend--m",
+        visually_hidden_label_prefix=None,
+        visually_hidden_label_suffix=None,
         classes=None,
         **kwargs,
     ):
@@ -68,6 +70,8 @@ def __init__(
         self.hint = hint
         self.classes = classes
         self.label_classes = label_classes
+        self.visually_hidden_label_prefix = visually_hidden_label_prefix
+        self.visually_hidden_label_suffix = visually_hidden_label_suffix
 
         super().__init__(*args, **kwargs)
 
@@ -100,6 +104,8 @@ def __init__(
         *args,
         hint=None,
         label_classes="nhsuk-fieldset__legend--m",
+        visually_hidden_label_prefix=None,
+        visually_hidden_label_suffix=None,
         classes=None,
         **kwargs,
     ):
@@ -108,5 +114,7 @@ def __init__(
         self.hint = hint
         self.classes = classes
         self.label_classes = label_classes
+        self.visually_hidden_label_prefix = visually_hidden_label_prefix
+        self.visually_hidden_label_suffix = visually_hidden_label_suffix
 
         super().__init__(*args, **kwargs)
diff --git a/manage_breast_screening/nhsuk_forms/fields/integer_field.py b/manage_breast_screening/nhsuk_forms/fields/integer_field.py
@@ -7,6 +7,8 @@ def __init__(
         *args,
         hint=None,
         label_classes=None,
+        visually_hidden_label_prefix=None,
+        visually_hidden_label_suffix=None,
         classes=None,
         inputmode="numeric",
         **kwargs,
@@ -16,6 +18,8 @@ def __init__(
         self.hint = hint
         self.classes = classes
         self.label_classes = label_classes
+        self.visually_hidden_label_prefix = visually_hidden_label_prefix
+        self.visually_hidden_label_suffix = visually_hidden_label_suffix
         self.inputmode = inputmode
 
         super().__init__(*args, **kwargs)
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/character-count.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/character-count.jinja
@@ -1,9 +1,10 @@
 {% from "character-count/macro.jinja" import characterCount %}
+{% from "forms/label.jinja" import label_html %}
 {% set unbound_field = field.field %}
 {% set widget = unbound_field.widget %}
 {% set character_count_params = {
     "label": {
-      "text": field.label,
+      "html": label_html(field),
       "classes": unbound_field.label_classes if unbound_field.label_classes
     },
     "hint": {
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/checkboxes.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/checkboxes.jinja
@@ -1,4 +1,5 @@
 {% from 'nhsuk/components/checkboxes/macro.jinja' import checkboxes %}
+{% from "forms/label.jinja" import label_html %}
 {% set unbound_field = field.field %}
 {% if field.errors %}
   {% set error_message = {"text": field.errors | first} %}
@@ -25,7 +26,7 @@
   "idPrefix": field.auto_id,
   "fieldset":  {
     "legend": {
-      "text": field.label,
+      "html": label_html(field),
       "classes": unbound_field.label_classes
     }
   } if field.use_fieldset else none,
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/input.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/input.jinja
@@ -1,15 +1,10 @@
 {% from "nhsuk/components/input/macro.jinja" import input %}
+{% from "forms/label.jinja" import label_html %}
 {% set unbound_field = field.field %}
 {% set widget = unbound_field.widget %}
-{% if unbound_field.visually_hidden_label_suffix %}
-  {% set label_html %}
-    {{ field.label }}<span class="nhsuk-u-visually-hidden">: {{ unbound_field.visually_hidden_label_suffix }}</span>
-  {% endset %}
-{% endif %}
 {% set input_params = {
     "label": {
-      "text": field.label,
-      "html": label_html if label_html,
+      "html": label_html(field),
       "classes": unbound_field.label_classes if unbound_field.label_classes
     },
     "hint": {
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/label.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/label.jinja
@@ -0,0 +1,10 @@
+{% macro label_html(field) %}
+  {% set unbound_field = field.field %}
+  {% if unbound_field.visually_hidden_label_prefix -%}
+  <span class="nhsuk-u-visually-hidden">{{ unbound_field.visually_hidden_label_prefix }}</span>
+  {% endif -%}
+  {{ field.label }}
+  {%- if unbound_field.visually_hidden_label_suffix -%}
+  <span class="nhsuk-u-visually-hidden">{{ unbound_field.visually_hidden_label_suffix }}</span>
+  {% endif %}
+{% endmacro %}
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/radios.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/radios.jinja
@@ -1,4 +1,5 @@
 {% from 'nhsuk/components/radios/macro.jinja' import radios %}
+{% from "forms/label.jinja" import label_html %}
 {% set unbound_field = field.field %}
 {% if field.errors %}
   {% set error_message = {"text": field.errors | first} %}
@@ -25,7 +26,7 @@
   "idPrefix": field.auto_id,
   "fieldset": {
     "legend": {
-      "text": field.label,
+      "html": label_html(field),
       "classes": unbound_field.label_classes
     }
   } if field.use_fieldset else none,
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/select.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/select.jinja
@@ -1,4 +1,5 @@
 {% from 'nhsuk/components/select/macro.jinja' import select as select %}
+{% from "forms/label.jinja" import label_html %}
 {% set unbound_field = field.field %}
 {% if field.errors %}
   {% set error_message = {"text": field.errors | first} %}
@@ -16,7 +17,10 @@
 {{ select({
   "name": field.html_name,
   "id": field.auto_id,
-  "label": {"text": field.label, "classes": unbound_field.label_classes},
+  "label": {
+    "html": label_html(field),
+    "classes": unbound_field.label_classes
+  },
   "errorMessage": error_message,
   "classes": unbound_field.classes if unbound_field.classes,
   "hint": {
diff --git a/manage_breast_screening/nhsuk_forms/jinja2/forms/textarea.jinja b/manage_breast_screening/nhsuk_forms/jinja2/forms/textarea.jinja
@@ -1,9 +1,10 @@
 {% from "textarea/macro.jinja" import textarea %}
+{% from "forms/label.jinja" import label_html %}
 {% set unbound_field = field.field %}
 {% set widget = unbound_field.widget %}
 {% set textarea_params = {
     "label": {
-      "text": field.label,
+      "html": label_html(field),
       "classes": unbound_field.label_classes if unbound_field.label_classes
     },
     "hint": {
diff --git a/manage_breast_screening/nhsuk_forms/tests/fields/test_char_field.py b/manage_breast_screening/nhsuk_forms/tests/fields/test_char_field.py
@@ -18,10 +18,15 @@ class TestForm(Form):
                 initial="somevalue",
                 label_classes="nhsuk-u-visually-hidden",
             )
+            field_with_visually_hidden_label_prefix = CharField(
+                label="Abc",
+                initial="somevalue",
+                visually_hidden_label_prefix="some prefix: ",
+            )
             field_with_visually_hidden_label_suffix = CharField(
                 label="Abc",
                 initial="somevalue",
-                visually_hidden_label_suffix="some suffix",
+                visually_hidden_label_suffix=": some suffix",
             )
             field_with_hint = CharField(
                 label="With hint", initial="", hint="ALL UPPERCASE"
@@ -89,6 +94,18 @@ def test_renders_nhs_input_with_visually_hidden_label(self, form_class):
             """,
         )
 
+    def test_renders_nhs_input_with_visually_hidden_label_prefix(self, form_class):
+        assertHTMLEqual(
+            form_class()["field_with_visually_hidden_label_prefix"].as_field_group(),
+            """
+            <div class="nhsuk-form-group">
+                <label class="nhsuk-label" for="id_field_with_visually_hidden_label_prefix">
+                    <span class="nhsuk-u-visually-hidden">some prefix: </span>Abc
+                </label><input class="nhsuk-input" id="id_field_with_visually_hidden_label_prefix" name="field_with_visually_hidden_label_prefix" type="text" value="somevalue">
+            </div>
+            """,
+        )
+
     def test_renders_nhs_input_with_visually_hidden_label_suffix(self, form_class):
         assertHTMLEqual(
             form_class()["field_with_visually_hidden_label_suffix"].as_field_group(),
diff --git a/manage_breast_screening/nhsuk_forms/tests/fields/test_choice_fields.py b/manage_breast_screening/nhsuk_forms/tests/fields/test_choice_fields.py
@@ -28,6 +28,13 @@ class TestForm(Form):
                 hint="Pick either one",
                 widget=Select,
             )
+            with_prefix_suffix = ChoiceField(
+                label="Abc",
+                visually_hidden_label_prefix="prefix: ",
+                visually_hidden_label_suffix=" - suffix",
+                choices=(("a", "A"), ("b", "B")),
+                hint="Pick either one",
+            )
             details = CharField(label="Abc", initial="")
 
         return TestForm
@@ -92,6 +99,33 @@ def test_renders_radios_with_conditional_html(self, form_class):
             """,
         )
 
+    def test_renders_labels_with_visually_hidden_text(self, form_class):
+        assertHTMLEqual(
+            form_class()["with_prefix_suffix"].as_field_group(),
+            """
+            <div class="nhsuk-form-group">
+                <fieldset aria-describedby="id_with_prefix_suffix-hint" class="nhsuk-fieldset">
+                    <legend class="nhsuk-fieldset__legend nhsuk-fieldset__legend--m">
+                        <span class="nhsuk-u-visually-hidden">prefix: </span>Abc<span class="nhsuk-u-visually-hidden"> - suffix</span>
+                    </legend>
+                    <div class="nhsuk-hint" id="id_with_prefix_suffix-hint">
+                        Pick either one
+                    </div>
+                    <div class="nhsuk-radios" data-module="nhsuk-radios">
+                        <div class="nhsuk-radios__item">
+                            <input class="nhsuk-radios__input" id="id_with_prefix_suffix" name="with_prefix_suffix" type="radio" value="a">
+                            <label class="nhsuk-label nhsuk-radios__label" for="id_with_prefix_suffix">A</label>
+                        </div>
+                        <div class="nhsuk-radios__item">
+                            <input class="nhsuk-radios__input" id="id_with_prefix_suffix-2" name="with_prefix_suffix" type="radio" value="b">
+                            <label class="nhsuk-label nhsuk-radios__label" for="id_with_prefix_suffix-2">B</label>
+                        </div>
+                    </div>
+                </fieldset>
+            </div>
+            """,
+        )
+
     def test_renders_nhs_select(self, form_class):
         assertHTMLEqual(
             form_class()["select_field"].as_field_group(),
diff --git a/manage_breast_screening/nhsuk_forms/tests/fields/test_integer_field.py b/manage_breast_screening/nhsuk_forms/tests/fields/test_integer_field.py
@@ -9,7 +9,13 @@ class TestIntegerField:
     @pytest.fixture
     def form_class(self):
         class TestForm(Form):
-            field = IntegerField(label="Abc", initial=1, max_value=10)
+            field = IntegerField(
+                label="Abc",
+                initial=1,
+                max_value=10,
+                visually_hidden_label_prefix="prefix: ",
+                visually_hidden_label_suffix=" - suffix",
+            )
 
         return TestForm
 
@@ -19,7 +25,7 @@ def test_renders_nhs_input(self, form_class):
             """
             <div class="nhsuk-form-group">
                 <label class="nhsuk-label" for="id_field">
-                    Abc
+                    <span class="nhsuk-u-visually-hidden">prefix: </span>Abc<span class="nhsuk-u-visually-hidden"> - suffix</span>
                 </label><input class="nhsuk-input" id="id_field" name="field" type="number" value="1" inputmode="numeric">
             </div>
             """,
