fix: include a visually hidden suffix in repeated labels

The "Describe the specific area" label is repeated for each
conditionally shown input.

Colin R pointed out that this can cause an accessibility problem when
using e.g. Dragon Naturally Speaking to control the browser. If multiple
elements on the same page have the same label, it won't know which you
mean. When javascript is working there should only be one of them
visible on the page, but the fields are still there.

Putting the unique part at the end should mean that the user can say the
label as it appears visually, "Describe the specific area" and Dragon
can prompt which one specifically they mean, e.g. "Describe the specific
area: right breast"

This should also workaround our tests in CI for some reason not running
the javascript that hides the non-selected fields. We may need
to look into this further, but it doesn't block this work.

Author: MatMoore

manage_breast_screening/mammograms/forms/symptom_forms.py

@@ -96,7 +96,11 @@ def area_radios(symptom_name="symptom"):
         )
 
     @staticmethod
-    def area_description(symptom_name="symptom", hint="For example, the left armpit"):
+    def area_description(
+        symptom_name="symptom",
+        hint="For example, the left armpit",
+        visually_hidden_label_suffix=None,
+    ):
         return CharField(
             required=False,
             label="Describe the specific area",
@@ -105,6 +109,7 @@ def area_description(symptom_name="symptom", hint="For example, the left armpit"
                 "required": f"Describe the specific area where the {symptom_name} is located"
             },
             classes="nhsuk-u-width-two-thirds",
+            visually_hidden_label_suffix=visually_hidden_label_suffix,
         )
 
 
@@ -224,9 +229,15 @@ def create(self, appointment, request):
 
 class LumpForm(SymptomForm):
     area = CommonFields.area_radios(symptom_name="lump")
-    area_description_right_breast = CommonFields.area_description("lump")
-    area_description_left_breast = CommonFields.area_description("lump")
-    area_description_other = CommonFields.area_description("lump")
+    area_description_right_breast = CommonFields.area_description(
+        "lump", visually_hidden_label_suffix="right breast"
+    )
+    area_description_left_breast = CommonFields.area_description(
+        "lump", visually_hidden_label_suffix="left breast"
+    )
+    area_description_other = CommonFields.area_description(
+        "lump", visually_hidden_label_suffix="other"
+    )
     when_started = CommonFields.when_started
     specific_date = CommonFields.specific_date
     intermittent = CommonFields.intermittent
@@ -255,12 +266,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"
+        "swelling or shape change", visually_hidden_label_suffix="right breast"
     )
     area_description_left_breast = CommonFields.area_description(
-        "swelling or shape change"
+        "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"
     )
-    area_description_other = CommonFields.area_description("swelling or shape change")
     when_started = CommonFields.when_started
     specific_date = CommonFields.specific_date
     intermittent = CommonFields.intermittent
@@ -292,9 +305,15 @@ 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")
-    area_description_left_breast = CommonFields.area_description("skin change")
-    area_description_other = CommonFields.area_description("skin change")
+    area_description_right_breast = CommonFields.area_description(
+        "skin change", visually_hidden_label_suffix="right breast"
+    )
+    area_description_left_breast = CommonFields.area_description(
+        "skin change", visually_hidden_label_suffix="left breast"
+    )
+    area_description_other = CommonFields.area_description(
+        "skin change", visually_hidden_label_suffix="other"
+    )
     symptom_sub_type = ChoiceField(
         choices=SkinChangeChoices,
         label="How has the skin changed?",
@@ -415,9 +434,15 @@ def area_initial(self, area):
 
 class OtherSymptomForm(SymptomForm):
     area = CommonFields.area_radios()
-    area_description_right_breast = CommonFields.area_description()
-    area_description_left_breast = CommonFields.area_description()
-    area_description_other = CommonFields.area_description()
+    area_description_right_breast = CommonFields.area_description(
+        visually_hidden_label_suffix="right breast"
+    )
+    area_description_left_breast = CommonFields.area_description(
+        visually_hidden_label_suffix="left breast"
+    )
+    area_description_other = CommonFields.area_description(
+        visually_hidden_label_suffix="other"
+    )
     symptom_sub_type_details = CharField(
         label="Describe the symptom",
         label_classes="nhsuk-label--m",

manage_breast_screening/nhsuk_forms/fields/char_field.py

@@ -9,6 +9,7 @@ def __init__(
         hint=None,
         label_classes=None,
         classes=None,
+        visually_hidden_label_suffix=None,
         **kwargs,
     ):
         widget = kwargs.get("widget")
@@ -22,6 +23,7 @@ def __init__(
         self.hint = hint
         self.classes = classes
         self.label_classes = label_classes
+        self.visually_hidden_label_suffix = visually_hidden_label_suffix
 
         super().__init__(*args, **kwargs)
 

manage_breast_screening/nhsuk_forms/jinja2/forms/input.jinja

@@ -1,9 +1,15 @@
 {% from "nhsuk/components/input/macro.jinja" import input %}
 {% 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,
       "classes": unbound_field.label_classes if unbound_field.label_classes
     },
     "hint": {

manage_breast_screening/nhsuk_forms/tests/fields/test_char_field.py

@@ -16,6 +16,11 @@ class TestForm(Form):
                 initial="somevalue",
                 label_classes="nhsuk-u-visually-hidden",
             )
+            field_with_visually_hidden_label_suffix = CharField(
+                label="Abc",
+                initial="somevalue",
+                visually_hidden_label_suffix="some suffix",
+            )
             field_with_hint = CharField(
                 label="With hint", initial="", hint="ALL UPPERCASE"
             )
@@ -73,6 +78,18 @@ def test_renders_nhs_input_with_visually_hidden_label(self, form_class):
             """,
         )
 
+    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(),
+            """
+            <div class="nhsuk-form-group">
+                <label class="nhsuk-label" for="id_field_with_visually_hidden_label_suffix">
+                    Abc<span class="nhsuk-u-visually-hidden">: some suffix</span>
+                </label><input class="nhsuk-input" id="id_field_with_visually_hidden_label_suffix" name="field_with_visually_hidden_label_suffix" type="text" value="somevalue">
+            </div>
+            """,
+        )
+
     def test_renders_nhs_input_with_hint(self, form_class):
         assertHTMLEqual(
             form_class()["field_with_hint"].as_field_group(),

manage_breast_screening/tests/system/clinical/test_recording_symptoms.py

@@ -96,12 +96,12 @@ def then_i_see_the_add_a_lump_form(self):
         self.assert_page_title_contains("Details of the lump")
 
     def when_i_select_right_breast(self):
-        self.page.get_by_label("Right breast").click()
+        self.page.get_by_label("Right breast", exact=True).click()
 
     def and_i_enter_the_area(self):
-        self.page.get_by_label("Describe the specific area").filter(visible=True).fill(
-            "ldq"
-        )
+        self.page.get_by_label("Describe the specific area: right breast").filter(
+            visible=True
+        ).fill("ldq")
 
     def and_i_select_less_than_three_months(self):
         self.page.get_by_label("Less than 3 months").click()