fix(material/list): fix selection-list staying in tab order when disabled

Remove list options from the tab order when the entire slection list is
disabled. Fix accessibility issue where end user can tab to a disabled selection
list.

```
<mat-selection-list disabled>
  <mat-list-option>A</mat-list-option>
  <!-- ^ should have tabindex="-1" since entire list is disabled -->
</mat-selection-list>
```

Approach is to consider a disabled mat-selection-list with a mat-list-option
having `tabindex="0"` an invalid state. When disabled Input on the seleciton
list is set to true, set tabindex to -1 on every list option.

fixes #25730

Author: zarend

src/material/list/list-base.ts

@@ -56,7 +56,9 @@ export abstract class MatListBase {
   }
   private _disableRipple: boolean = false;
 
-  /** Whether all list items are disabled. */
+  /**
+   * Whether the *entire* list is disabled. When true, each list item is also disabled.
+   */
   @Input()
   get disabled(): boolean {
     return this._disabled;

src/material/list/selection-list.spec.ts

@@ -804,6 +804,29 @@ describe('MDC-based MatSelectionList without forms', () => {
         .withContext('Expected ripples of list option to be enabled')
         .toBe(false);
     });
+
+    // when the entire list is disabled, its listitems should always have tabindex="-1"
+    it('should not put listitems in the tab order', () => {
+      fixture.componentInstance.disabled = false;
+      let testListItem = listOption[2].injector.get<MatListOption>(MatListOption);
+      testListItem.focus();
+      fixture.detectChanges();
+
+      expect(
+        listOption.filter(option => option.nativeElement.getAttribute('tabindex') === '0').length,
+      )
+        .withContext('Expected at least one list option to be in the tab order')
+        .toBeGreaterThanOrEqual(1);
+
+      fixture.componentInstance.disabled = true;
+      fixture.detectChanges();
+
+      expect(
+        listOption.filter(option => option.nativeElement.getAttribute('tabindex') !== '-1').length,
+      )
+        .withContext('Expected all list options to be excluded from the tab order')
+        .toBe(0);
+    });
   });
 
   describe('with checkbox position after', () => {
@@ -1373,12 +1396,20 @@ describe('MDC-based MatSelectionList with forms', () => {
     });
 
     it('should be able to disable options from the control', () => {
+      selectionList.focus();
       expect(selectionList.disabled)
         .withContext('Expected the selection list to be enabled.')
         .toBe(false);
       expect(listOptions.every(option => !option.disabled))
         .withContext('Expected every list option to be enabled.')
         .toBe(true);
+      expect(
+        listOptions.some(
+          option => option._elementRef.nativeElement.getAttribute('tabindex') === '0',
+        ),
+      )
+        .withContext('Expected one list item to be in the tab order')
+        .toBe(true);
 
       fixture.componentInstance.formControl.disable();
       fixture.detectChanges();
@@ -1389,6 +1420,13 @@ describe('MDC-based MatSelectionList with forms', () => {
       expect(listOptions.every(option => option.disabled))
         .withContext('Expected every list option to be disabled.')
         .toBe(true);
+      expect(
+        listOptions.every(
+          option => option._elementRef.nativeElement.getAttribute('tabindex') === '-1',
+        ),
+      )
+        .withContext('Expected every list option to be removed from the tab order')
+        .toBe(true);
     });
 
     it('should be able to update the disabled property after form control disabling', () => {

src/material/list/selection-list.ts

@@ -57,6 +57,20 @@ export class MatSelectionListChange {
   ) {}
 }
 
+/**
+ * Determines if key manager should avoid putting a given list item in the tab index. Allow
+ * disabled list items to receive focus to align with WAI ARIA recommendation. Normally WAI ARIA's
+ * instructions are to exclude disabled items from the tab order, but it makes a few exceptions for
+ * compound widgets.
+ *
+ * From [Developing a Keyboard Interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/):
+ *   "For the following composite widget elements, keep them focusable when disabled: Options in a
+ *   Listbox..."
+ */
+function _skipPredicate(_option: MatListOption): boolean {
+  return false;
+}
+
 @Component({
   selector: 'mat-selection-list',
   exportAs: 'matSelectionList',
@@ -230,6 +244,23 @@ export class MatSelectionList
     this.disabled = isDisabled;
   }
 
+  /**
+   * Whether the *entire* selection list is disabled. When true, each list item is also disabled
+   * and each list item is removed from the tab order (has tabindex="-1").
+   */
+  @Input()
+  override get disabled(): boolean {
+    return super.disabled;
+  }
+  override set disabled(value: BooleanInput) {
+    super.disabled = value;
+    if (super.disabled) {
+      // When the entire list is disabled, remove all list items from the tab order. Fix bug where
+      // selection list stays in the tab order after being disabled.
+      this._keyManager?.setActiveItem(-1);
+    }
+  }
+
   /** Implemented as part of ControlValueAccessor. */
   registerOnChange(fn: (value: any) => void): void {
     this._onChange = fn;
@@ -371,8 +402,7 @@ export class MatSelectionList
       .withHomeAndEnd()
       .withTypeAhead()
       .withWrap()
-      // Allow navigation to disabled items.
-      .skipPredicate(() => false);
+      .skipPredicate(_skipPredicate);
 
     // Set the initial focus.
     this._resetActiveOption();

tools/public_api_guard/material/list.md

@@ -215,6 +215,8 @@ export class MatSelectionList extends MatListBase implements SelectionList, Cont
     color: ThemePalette;
     compareWith: (o1: any, o2: any) => boolean;
     deselectAll(): MatListOption[];
+    get disabled(): boolean;
+    set disabled(value: BooleanInput);
     // (undocumented)
     _element: ElementRef<HTMLElement>;
     _emitChangeEvent(options: MatListOption[]): void;
@@ -242,7 +244,7 @@ export class MatSelectionList extends MatListBase implements SelectionList, Cont
     _value: string[] | null;
     writeValue(values: string[]): void;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatSelectionList, "mat-selection-list", ["matSelectionList"], { "color": "color"; "compareWith": "compareWith"; "multiple": "multiple"; }, { "selectionChange": "selectionChange"; }, ["_items"], ["*"], false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatSelectionList, "mat-selection-list", ["matSelectionList"], { "color": "color"; "compareWith": "compareWith"; "multiple": "multiple"; "disabled": "disabled"; }, { "selectionChange": "selectionChange"; }, ["_items"], ["*"], false, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatSelectionList, never>;
 }