Edit File Modal Keyboard Trap

[dhweddington]

@lgeggleston
Issue reported by University of Virginia (UVA) Library’s Assessment, Communications, and User Experience (ACE) team as part of internal DSpace 9 accessibility audit.

Issue 1 of 2: Edit File Modal Keyboard Trap

Describe the bug

Specifically in Safari, when the modal opens, keyboard focus is not properly managed. Users can tab out of the modal into background content and cannot tab back in, creating a functional keyboard trap. It appears to happen when UVA only or Embargo are selected. This violates the required modal dialog behavior defined in WCAG: Users must be able to move focus into and out of components using only the keyboard. The modal currently allows focus to escape but not return. When the modal appears, focus must move into it and remain within it until dismissed, preserving logical interaction order. The modal container lacks an accessible name via aria-labelledby, which can cause AT/browser combinations to incorrectly handle dialog focus. This issue blocks users from interacting with or closing the modal using keyboard-only navigation, making the modal inoperable for many users. Also affects: 2.1.2 No Keyboard Trap (Level A), 2.4.3 Focus Order (Level A), 4.1.2 Name, Role, Value (Level A)

Page

Upload Item (Form)

WCAG Guideline

WCAG 2.1.1, 2.1.2, 2.4.3, and 4.1.2

To Reproduce

Relevant code

Start of code: \<ngb-modal-window role="dialog" tabindex="-1" aria-modal="true" class="d-block modal fade show"\>\<div role="document" class="modal-dialog modal-xl"\>\<div class="modal-content"\>

Expected behavior

Move focus into the modal when it opens: Focus has to move to the first meaningful control immediately when the modal appears. This is usually the close button, but can also be the first field. Trap focus inside the modal while it is open: Tab and Shift+Tab have to move only within the modal elements. The background content shouldn't receive focus. Ensure the modal has an accessible name Add an id to the title and reference it via aria-labelledby on the modal container Return focus to the button that opened the modal when it closes Retain the current functionality of closing modal by pressing Esc

Suggested fix / example code

Adding accessible name: \<ngb-modal-window role="dialog" aria-modal="true" aria-labelledby="edit-file-title" tabindex="-1"\> \<div class="modal-dialog modal-xl"\> \<div class="modal-content"\> \<div class="modal-header"\> \<h4 id="edit-file-title" class="modal-title"\>Edit file\</h4\> \<button type="button" class="btn-close" aria-label="Close"\>\</button\> \</div\> \<!-- modal body --\> \</div\>\</div\>\</ngb-modal-window\> Please note: the Javascript below are examples, but I didn't dive into the JS. The general functionality of what should be happening should hopefully be clear enough that you can make edits as needed. Move focus into modal when opened: // Called when opening the modal ngAfterViewInit() { const closeBtn = this.elementRef.nativeElement.querySelector('.btn-close'); (closeBtn || this.elementRef.nativeElement).focus();} Trap focus into modal: @HostListener('keydown', ['$event']) handleTabTrap(event: KeyboardEvent) { const focusableSelectors = [ 'button:not([disabled])', '[href]', 'input:not([disabled])', 'select:not([disabled])', 'textarea:not([disabled])', '[tabindex]:not([tabindex="-1"])' ]; const modal = this.elementRef.nativeElement; const focusable = Array.from(modal.querySelectorAll(focusableSelectors)); const first = focusable[0]; const last = focusable[focusable.length - 1]; if (event.key === 'Tab') { // Shift + Tab if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus();} // Tab forward else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus();}}} Restore focus on close: // Before opening the modal storeTrigger(triggerElement: HTMLElement) { this.triggerEl = triggerElement;} // On modal close ngOnDestroy() { this.triggerEl?.focus();}

Issue 2 of 2: Edit File Modal Keyboard Trap

Describe the bug

Specifically in Safari, when the modal opens, keyboard focus is not properly managed. Users can tab out of the modal into background content and cannot tab back in, creating a functional keyboard trap. It appears to happen when UVA only or Embargo are selected. This violates the required modal dialog behavior defined in WCAG: Users must be able to move focus into and out of components using only the keyboard. The modal currently allows focus to escape but not return. When the modal appears, focus must move into it and remain within it until dismissed, preserving logical interaction order. The modal container lacks an accessible name via aria-labelledby, which can cause AT/browser combinations to incorrectly handle dialog focus. This issue blocks users from interacting with or closing the modal using keyboard-only navigation, making the modal inoperable for many users.

Page

Upload Person (Form)

WCAG Guideline

WCAG 2.1.1, 2.1.2, 2.4.3, 4.1.2

To Reproduce

Relevant code

Start of code snippet: \<ngb-modal-window role="dialog" tabindex="-1" aria-modal="true" class="d-block modal fade show"\>\<div role="document" class="modal-dialog modal-xl"\>\<div class="modal-content"\>\<ds-submission-section-upload-file-edit \_nghost-dspace-angular-c3076456883=""\>\<div \_ngcontent-dspace-angular-c3076456883=""\>\<div \_ngcontent-dspace-angular-c3076456883="" class="modal-header"\>\<h4 \_ngcontent-dspace-angular-c3076456883="" class="modal-title"\>Edit file\</h4\>\<button \_ngcontent-dspace-angular-c3076456883="" type="button" aria-label="Close" class="

Expected behavior

Move focus into the modal when it opens: Focus has to move to the first meaningful control immediately when the modal appears. This is usually the close button, but can also be the first field. Trap focus inside the modal while it is open: Tab and Shift+Tab have to move only within the modal elements. The background content shouldn't receive focus. Ensure the modal has an accessible name Add an id to the title and reference it via aria-labelledby on the modal container Return focus to the button that opened the modal when it closes Retain the current functionality of closing modal by pressing Esc

Suggested fix / example code

Adding accessible name: \<ngb-modal-window role="dialog" aria-modal="true" aria-labelledby="edit-file-title" tabindex="-1"\>\<div class="modal-dialog modal-xl"\>\<div class="modal-content"\>\<div class="modal-header"\>\<h4 id="edit-file-title" class="modal-title"\>Edit file\</h4\>\<button type="button" class="btn-close" aria-label="Close"\>\</button\>\</div\>\</div\> \</div\>\</ngb-modal-window\> Please note: the Javascript below are examples, but I didn't dive into the JS. The general functionality of what should be happening should hopefully be clear enough that you can make edits as needed. Move focus into modal when opened: // Called when opening the modal ngAfterViewInit() { const closeBtn = this.elementRef.nativeElement.querySelector('.btn-close'); (closeBtn || this.elementRef.nativeElement).focus();} Trap focus into modal: @HostListener('keydown', ['$event']) handleTabTrap(event: KeyboardEvent) { const focusableSelectors = [ 'button:not([disabled])', '[href]', 'input:not([disabled])', 'select:not([disabled])', 'textarea:not([disabled])', '[tabindex]:not([tabindex="-1"])' ]; const modal = this.elementRef.nativeElement; const focusable = Array.from(modal.querySelectorAll(focusableSelectors)); const first = focusable[0]; const last = focusable[focusable.length - 1]; if (event.key === 'Tab') { // Shift + Tab if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); } // Tab forward else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); } }} Restore focus on close: // Before opening the modal storeTrigger(triggerElement: HTMLElement) { this.triggerEl = triggerElement;} // On modal close ngOnDestroy() { this.triggerEl?.focus();}

Related work

#5502

[lgeggleston]

Hi @dhweddington, thanks for adding!
To note: Issues 1 & 2 appear to be the same issue (no need to differentiate between default item & Person upload that I can tell), so would be best to remove one.

The issue linked (#5502) and open PR #5506 appear to address at least a part of this (ARIA labelling), but it looks like there are changes beyond that suggested here. If your team would like to test or get further into the details of the open PR, we may be able to separate out what is not yet addressed there. Thanks!