#3181 - dynamic labels for investigator and senior official [-Bob] #3577

CocoByte · 2025-02-27T01:29:08Z

Ticket 3181

Resolves #3181

Changes

Added overrides that target select2 dropdowns and add aria-describedby text in accordance with the ticket's ACs.

Context for reviewers

The two dropdowns listed in the original ACs really just highlight a more systemic issue with our ARIA labels for select2 dropdowns. The updates for this ticket addresses all select2 components throughout Django Admin so they will all follow the same pattern.

Setup

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

Met the acceptance criteria, or will meet them in a subsequent PR
Created/modified automated tests
Update documentation in READMEs and/or onboarding guide

Ensured code standards are met (Original Developer)

If any updated dependencies on Pipfile, also update dependencies in requirements.txt.
Interactions with external systems are wrapped in try/except
Error handling exists for unusual or missing values

Validated user-facing changes (if applicable)

Tag @dotgov-designers in this PR's Reviewers for design review. If code is not user-facing, delete design reviewer checklist
Verify new pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
Checked keyboard navigability
Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)

As a code reviewer, I have

Reviewed, tested, and left feedback about the changes

Pulled this branch locally and tested it
Verified code meets all checks above. Address any checks that are not satisfied
Reviewed this code and left comments. Indicate if comments must be addressed before code is merged
Checked that all code is adequately covered by tests
Verify migrations are valid and do not conflict with existing migrations

Validated user-facing changes as a developer

Note: Multiple code reviewers can share the checklists above, a second reviewer should not make a duplicate checklist. All checks should be checked before approving, even those labeled N/A.

New pages have been added to .pa11yci file so that they will be tested with our automated accessibility testing
Checked keyboard navigability
Meets all designs and user flows provided by design/product
Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
(Rarely needed) Tested as both an analyst and applicant user

As a designer reviewer, I have

Verified that the changes match the design intention

Checked that the design translated visually
Checked behavior. Comment any found issues or broken flows.
Checked different states (empty, one, some, error)
Checked for landmarks, page heading structure, and links

Validated user-facing changes as a designer

Checked keyboard navigability
Tested general usability, landmarks, page header structure, and links with a screen reader (such as Voiceover or ANDI)
Tested with multiple browsers (check off which ones were used)
- Chrome
- Microsoft Edge
- FireFox
- Safari
(Rarely needed) Tested as both an analyst and applicant user

References

Code review best practices

Screenshots

zandercymatics

Just needs some cleanup, but everything is here! I like how you are addressing this holistically, which is a very nice touch

src/registrar/admin.py

zandercymatics · 2025-02-28T15:51:02Z

src/registrar/assets/src/js/getgov-admin/andi.js

+This allows us to avoid overriding aria-label, which is used by select2
+to send the current dropdown selection to ANDI
+*/
+export function initAriaInjections() {


Could you rename this to something similar to initAriaInjectionsForSelect2? Would be more descriptive for someone unfamiliar with this part of the codebase

src/registrar/assets/src/js/getgov-admin/andi.js

zandercymatics · 2025-02-28T16:09:52Z

src/registrar/assets/src/js/getgov-admin/andi.js

+        setTimeout(function () {
+            // Find all spans with "--aria-description" in their id
+            const descriptionSpans = document.querySelectorAll('span[id*="--aria-description"]');
+
+            // Iterate through each span to add aria-describedby
+            descriptionSpans.forEach(function(span) {
+                // Extract the base ID from the span's id (remove "--aria-description" part)
+                const fieldId = span.id.replace('--aria-description', '');
+
+                // Find the field element with the corresponding ID
+                const field = document.getElementById(fieldId);
+
+                // If the field exists, set the aria-describedby attribute
+                if (field) {
+                    let select2ElementDetected = false
+                    if (field.classList.contains('admin-autocomplete')) {
+                        const select2Id="select2-"+fieldId+"-container"
+                        console.log("select2---> "+select2Id)
+                        // If it's a Select2 component, find the rendered span inside Select2
+                        const select2SpanThatTriggersAria = document.querySelector("span[aria-labelledby='"+select2Id+"']");
+                        const select2SpanThatHoldsSelection = document.getElementById(select2Id)
+                        if (select2SpanThatTriggersAria) {
+                            console.log("set select2 aria")
+                            select2SpanThatTriggersAria.setAttribute('aria-describedby', span.id);
+                            // select2SpanThatTriggersAria.setAttribute('aria-labelledby', select2Id);
+                            select2ElementDetected=true
+                        }
+                    } 


This works but this is definitely a workaround for select2 weirdness! I think this on its own should be fine but I'd like to try another solution first

I haven't tested it but according to select2's docs you can check if its intialized as so: https://select2.org/programmatic-control/methods#checking-if-the-plugin-is-initialized. Then you might be able to use a mutationObserver. If this works, it would be this would be less flaky overall since the load time can vary per machine

One thing to note is that instead of the $ icon, django admin binds it to django.jQuery

// check if it's already initialized if ($('#mySelect2').hasClass("select2-hidden-accessible")) { console.log("Select2 already initialized when we checked"); // do some stuff return; } const observer = new MutationObserver(function(mutations) { if (django.jQuery(`#${select2Id}`).hasClass("select2-hidden-accessible")) { console.log("initialized"); // Stop observing once initialized observer.disconnect(); } }); observer.observe(document.body, { childList: true, subtree: true });

I'm so glad you brought this up. I hate relying on timeouts, so thanks for the suggestion. I'll give it a try

zandercymatics · 2025-02-28T16:23:52Z

src/registrar/assets/src/js/getgov-admin/andi.js

+        // Set timeout so this fires after select2.js finishes adding to the DOM
+        setTimeout(function () {
+            // Find all spans with "--aria-description" in their id
+            const descriptionSpans = document.querySelectorAll('span[id*="--aria-description"]');


I can't find this in the dom - which page are you finding this id on?

This is nested in components on pages like admin --> change domain request

zandercymatics · 2025-02-28T16:34:55Z

src/registrar/templates/django/admin/includes/detail_table_fieldset.html

+    {% if "related_widget_wrapper" in field.field.field.widget.template_name %}
+        <span id="{{ field.field.id_for_label }}--aria-description" class="visually-hidden admin-select--aria-description">
+            {{ field.field.label }}, combo-box, collapsed, edit, has autocomplete. To set the value, use the arrow keys or type the text.
+        </span>
+    {% endif %}


This check is magic to me, nice job 😄

zandercymatics · 2025-02-28T16:40:04Z

src/registrar/templates/django/admin/includes/detail_table_fieldset.html

+    {% endcomment %}
+    {% if "related_widget_wrapper" in field.field.field.widget.template_name %}
+        <span id="{{ field.field.id_for_label }}--aria-description" class="visually-hidden admin-select--aria-description">
+            {{ field.field.label }}, combo-box, collapsed, edit, has autocomplete. To set the value, use the arrow keys or type the text.


@SamiyahKey / @CocoByte I think the andi content should be different here. With narrator this reads: Combobox, collapsed. Investigator, combo-box, collapsed, edit, has autocomplete. To set the value, use the arrow keys or type the text.

I would propose that this should be:
Edit, has autocomplete. To set the value, use the arrow keys or type the text. since screenreaders will append the combobox information for us

Also - per the andi warning, this should have a aria-labelledby! It should be aria-labelledby=${id_of_title} so the screenreader will automatically read out that this is associated with investigator, rather than us having to add it manually

Yes @zandercymatics I agree! Also the form field for "Senior official" still needs to be corrected, right now there still needs to be an accessible name added to the senior official field to tie with that aria-describedby

No can do with select2. That attr is already used

@zandercymatics can you think of a possibility to handle this senior official field?

zandercymatics · 2025-02-28T16:43:00Z

src/registrar/assets/src/js/getgov-admin/andi.js

+                        if (select2SpanThatTriggersAria) {
+                            console.log("set select2 aria")
+                            select2SpanThatTriggersAria.setAttribute('aria-describedby', span.id);
+                            // select2SpanThatTriggersAria.setAttribute('aria-labelledby', select2Id);


Can you clean up some of the old comments and logs here?

nice catch - thanks!

Co-authored-by: zandercymatics <[email protected]>

github-actions · 2025-02-28T19:02:12Z

🥳 Successfully deployed to developer sandbox nl.

…fficial

github-actions · 2025-03-01T00:24:25Z

🥳 Successfully deployed to developer sandbox nl.

CocoByte added 2 commits February 26, 2025 13:45

initial draft (need to fix DOM targeting)

4bcb5bf

updates

8250a72

CocoByte changed the title ~~[DRAFT] #3181 - dynamic labels for investigator and senior official~~ #3181 - dynamic labels for investigator and senior official [-Bob] Feb 27, 2025

CocoByte requested review from zandercymatics, dave-kennedy-ecs, rachidatecs, therealslimhsiehdy, Matt-Spence, erinysong and SamiyahKey and removed request for zandercymatics and dave-kennedy-ecs February 27, 2025 17:51

zandercymatics self-assigned this Feb 28, 2025

zandercymatics requested changes Feb 28, 2025

View reviewed changes

SamiyahKey requested review from kimmsie and removed request for kimmsie February 28, 2025 17:15

CocoByte and others added 2 commits February 28, 2025 11:10

Update src/registrar/assets/src/js/getgov-admin/andi.js

8d2a247

Co-authored-by: zandercymatics <[email protected]>

resolve merge conflicts

1365272

Merge branch 'main' into nl/3181-labels-for-investigator-and-senior-o…

5e79f98

…fficial

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

#3181 - dynamic labels for investigator and senior official [-Bob] #3577

#3181 - dynamic labels for investigator and senior official [-Bob] #3577

CocoByte commented Feb 27, 2025

zandercymatics left a comment

zandercymatics Feb 28, 2025

zandercymatics Feb 28, 2025

CocoByte Feb 28, 2025

zandercymatics Feb 28, 2025

CocoByte Feb 28, 2025

zandercymatics Feb 28, 2025

zandercymatics Feb 28, 2025

zandercymatics Feb 28, 2025

SamiyahKey Feb 28, 2025

CocoByte Feb 28, 2025

SamiyahKey Feb 28, 2025

zandercymatics Feb 28, 2025

CocoByte Feb 28, 2025

github-actions bot commented Feb 28, 2025

github-actions bot commented Mar 1, 2025

#3181 - dynamic labels for investigator and senior official [-Bob] #3577

Are you sure you want to change the base?

#3181 - dynamic labels for investigator and senior official [-Bob] #3577

Conversation

CocoByte commented Feb 27, 2025

Ticket 3181

Changes

Context for reviewers

Setup

Code Review Verification Steps

As the original developer, I have

Satisfied acceptance criteria and met development standards

Ensured code standards are met (Original Developer)

Validated user-facing changes (if applicable)

As a code reviewer, I have

Reviewed, tested, and left feedback about the changes

Validated user-facing changes as a developer

As a designer reviewer, I have

Verified that the changes match the design intention

Validated user-facing changes as a designer

References

Screenshots

zandercymatics left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Feb 28, 2025

github-actions bot commented Mar 1, 2025