fix(material/list): add radio toggles

Add radio toggles for single selection. Fix a11y issue where selected
state is visually communicated with color alone.

Add `togglePosition` Input, which configures the position of both the
radio and checkbox. Deprecates `checkboxPosition`, which will configure
the position of both the radio and checkbox.

Summary of API and behavior changes
 - MDC List displays radio indicators for single-selection
 - add `togglePosition` Input to to configure position of both radio and
   checkbox
 - deprecate `checkboxPosition`, which is a shim for `togglePosition`

Closes #7157, Fixes #25900

Author: zarend

src/dev-app/list/list-demo.html

@@ -126,21 +126,21 @@ <h2>Selection list</h2>
                         color="primary">
       <div mat-subheader>Groceries</div>
 
-      <mat-list-option value="bananas" checkboxPosition="before">Bananas</mat-list-option>
-      <mat-list-option selected value="oranges">Oranges</mat-list-option>
-      <mat-list-option value="apples" color="accent">Apples</mat-list-option>
-      <mat-list-option value="strawberries" color="warn">Strawberries</mat-list-option>
+      <mat-list-option value="bananas" togglePosition="before">Bananas</mat-list-option>
+      <mat-list-option selected value="oranges" color="accent">Oranges</mat-list-option>
+      <mat-list-option value="apples" color="warn">Apples</mat-list-option>
+      <mat-list-option value="strawberries" disabled>Strawberries</mat-list-option>
     </mat-selection-list>
 
     <mat-selection-list [disableRipple]="selectionListRippleDisabled">
       <div mat-subheader>Dogs</div>
 
-      <mat-list-option checkboxPosition="before">
+      <mat-list-option togglePosition="before">
         <img matListItemAvatar src="https://material.angular.io/assets/img/examples/shiba1.jpg">
         <span matListItemTitle>Shiba Inu</span>
       </mat-list-option>
 
-      <mat-list-option checkboxPosition="after">
+      <mat-list-option togglePosition="after">
         <img matListItemAvatar src="https://material.angular.io/assets/img/examples/shiba2.jpg">
         <span matListItemTitle>Other Shiba Inu</span>
       </mat-list-option>
@@ -177,9 +177,9 @@ <h2>Single Selection list</h2>
       <div mat-subheader>Favorite Grocery</div>
 
       <mat-list-option value="bananas">Bananas</mat-list-option>
-      <mat-list-option selected value="oranges">Oranges</mat-list-option>
-      <mat-list-option value="apples">Apples</mat-list-option>
-      <mat-list-option value="strawberries" color="warn">Strawberries</mat-list-option>
+      <mat-list-option selected value="oranges" color="accent">Oranges</mat-list-option>
+      <mat-list-option value="apples" color="warn">Apples</mat-list-option>
+      <mat-list-option value="strawberries" disabled>Strawberries</mat-list-option>
     </mat-selection-list>
 
     <p>Selected: {{favoriteOptions | json}}</p>
@@ -239,19 +239,19 @@ <h2>Line alignment</h2>
     <h2>Icon alignment in selection list</h2>
 
     <mat-selection-list>
-      <mat-list-option value="bananas" [checkboxPosition]="checkboxPosition">
+      <mat-list-option value="bananas" [togglePosition]="togglePosition">
         <mat-icon matListItemIcon>info</mat-icon>
         Bananas
       </mat-list-option>
-      <mat-list-option value="oranges" [checkboxPosition]="checkboxPosition">
+      <mat-list-option value="oranges" [togglePosition]="togglePosition">
         <mat-icon matListItemIcon #ok>info</mat-icon>
         Oranges
       </mat-list-option>
-      <mat-list-option value="cake" [checkboxPosition]="checkboxPosition">
+      <mat-list-option value="cake" [togglePosition]="togglePosition">
         <mat-icon matListItemIcon>info</mat-icon>
         Cake
       </mat-list-option>
-      <mat-list-option value="fries" [checkboxPosition]="checkboxPosition">
+      <mat-list-option value="fries" [togglePosition]="togglePosition">
         <mat-icon matListItemIcon>info</mat-icon>
         Fries
       </mat-list-option>

src/dev-app/list/list-demo.ts

@@ -9,7 +9,7 @@
 import {Component} from '@angular/core';
 import {FormsModule} from '@angular/forms';
 import {MatButtonModule} from '@angular/material/button';
-import {MatListModule, MatListOptionCheckboxPosition} from '@angular/material/list';
+import {MatListModule, MatListOptionTogglePosition} from '@angular/material/list';
 import {MatIconModule} from '@angular/material/icon';
 import {CommonModule} from '@angular/common';
 
@@ -23,7 +23,7 @@ import {CommonModule} from '@angular/common';
 export class ListDemo {
   items: string[] = ['Pepper', 'Salt', 'Paprika'];
 
-  checkboxPosition: MatListOptionCheckboxPosition = 'before';
+  togglePosition: MatListOptionTogglePosition = 'before';
 
   contacts: {name: string; headline: string}[] = [
     {name: 'Nancy', headline: 'Software engineer'},
@@ -75,7 +75,7 @@ export class ListDemo {
   }
 
   toggleCheckboxPosition() {
-    this.checkboxPosition = this.checkboxPosition === 'before' ? 'after' : 'before';
+    this.togglePosition = this.togglePosition === 'before' ? 'after' : 'before';
   }
 
   favoriteOptions: string[] = [];

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

@@ -74,7 +74,7 @@ export class MatLegacySelectionListChange {
 /**
  * Type describing possible positions of a checkbox in a list option
  * with respect to the list item's text.
- * @deprecated Use `MatListOptionCheckboxPosition` from `@angular/material/list` instead. See https://material.angular.io/guide/mdc-migration for information about migrating.
+ * @deprecated Use `MatListOptionTogglePosition` from `@angular/material/list` instead. See https://material.angular.io/guide/mdc-migration for information about migrating.
  * @breaking-change 17.0.0
  */
 export type MatLegacyListOptionCheckboxPosition = 'before' | 'after';

src/material/list/BUILD.bazel

@@ -52,6 +52,7 @@ sass_library(
         "//:mdc_sass_lib",
         "//src/material/checkbox:checkbox_scss_lib",
         "//src/material/core:core_scss_lib",
+        "//src/material/radio:radio_scss_lib",
     ],
 )
 

src/material/list/_list-option-theme.scss

@@ -2,13 +2,15 @@
 @use '../core/mdc-helpers/mdc-helpers';
 @use '../checkbox/checkbox-private';
 @use './list-option-trailing-avatar-compat';
+@use '../radio/radio-private';
 
 // Mixin that overrides the selected item and checkbox colors for list options. By
 // default, the MDC list uses the `primary` color for list items. The MDC checkbox
 // inside list options by default uses the `primary` color too.
 @mixin private-list-option-color-override($color-config, $color, $mdc-color) {
   & .mdc-list-item__start, & .mdc-list-item__end {
     @include checkbox-private.private-checkbox-styles-with-color($color-config, $color, $mdc-color);
+    @include radio-private.private-radio-color($color-config, $color);
   }
 }
 

src/material/list/list-item-sections.ts

@@ -72,8 +72,8 @@ export class _MatListItemGraphicBase {
 
   _isAlignedAtStart() {
     // By default, in all list items the graphic is aligned at start. In list options,
-    // the graphic is only aligned at start if the checkbox is at the end.
-    return !this._listOption || this._listOption?._getCheckboxPosition() === 'after';
+    // the graphic is only aligned at start if the checkbox/radio is at the end.
+    return !this._listOption || this._listOption?._getTogglePosition() === 'after';
   }
 }
 

src/material/list/list-option-types.ts

@@ -9,18 +9,27 @@
 import {InjectionToken} from '@angular/core';
 
 /**
- * Type describing possible positions of a checkbox in a list option
+ * Type describing possible positions of a checkbox or radio in a list option
  * with respect to the list item's text.
+ *
+ * @deprecated Use `MatListOptionTogglePosition` instead.
+ * @breaking-change 17.0.0
  */
 export type MatListOptionCheckboxPosition = 'before' | 'after';
 
+/**
+ * Type describing possible positions of a checkbox or radio in a list option
+ * with respect to the list item's text.
+ */
+export type MatListOptionTogglePosition = 'before' | 'after';
+
 /**
  * Interface describing a list option. This is used to avoid circular
  * dependencies between the list-option and the styler directives.
  * @docs-private
  */
 export interface ListOption {
-  _getCheckboxPosition(): MatListOptionCheckboxPosition;
+  _getTogglePosition(): MatListOptionTogglePosition;
 }
 
 /**

src/material/list/list-option.html

@@ -25,11 +25,27 @@
   </div>
 </ng-template>
 
+<ng-template #radio>
+  <div class="mdc-radio" [class.mdc-radio--disabled]="disabled">
+    <input type="radio" class="mdc-radio__native-control"
+           [checked]="selected" [disabled]="disabled"/>
+    <div class="mdc-radio__background">
+      <div class="mdc-radio__outer-circle"></div>
+      <div class="mdc-radio__inner-circle"></div>
+    </div>
+  </div>
+</ng-template>
+
 <!-- Container for the checkbox at start. -->
 <span class="mdc-list-item__start mat-mdc-list-option-checkbox-before"
       *ngIf="_hasCheckboxAt('before')">
   <ng-template [ngTemplateOutlet]="checkbox"></ng-template>
 </span>
+<!-- Container for the radio at the start. -->
+<span class="mdc-list-item__start mat-mdc-list-option-radio-before"
+      *ngIf="_hasRadioAt('before')">
+  <ng-template [ngTemplateOutlet]="radio"></ng-template>
+</span>
 <!-- Conditionally renders icons/avatars before the list item text. -->
 <ng-template [ngIf]="_hasIconsOrAvatarsAt('before')">
   <ng-template [ngTemplateOutlet]="icons"></ng-template>
@@ -49,6 +65,10 @@
 <span class="mdc-list-item__end" *ngIf="_hasCheckboxAt('after')">
   <ng-template [ngTemplateOutlet]="checkbox"></ng-template>
 </span>
+<!-- Container for the radio at the end. -->
+<span class="mdc-list-item__end" *ngIf="_hasRadioAt('after')">
+  <ng-template [ngTemplateOutlet]="radio"></ng-template>
+</span>
 <!-- Conditionally renders icons/avatars after the list item text. -->
 <ng-template [ngIf]="_hasIconsOrAvatarsAt('after')">
   <ng-template [ngTemplateOutlet]="icons"></ng-template>

src/material/list/list-option.scss

@@ -1,9 +1,12 @@
 @use 'sass:map';
 @use '@material/checkbox/checkbox' as mdc-checkbox;
 @use '@material/checkbox/checkbox-theme' as mdc-checkbox-theme;
+@use '@material/radio/radio' as mdc-radio;
+@use '@material/radio/radio-theme' as mdc-radio-theme;
 
 @use '../core/mdc-helpers/mdc-helpers';
 @use '../checkbox/checkbox-private';
+@use '../radio/radio-private';
 @use './list-option-trailing-avatar-compat';
 @use './list-item-hcm-indicator';
 
@@ -17,30 +20,44 @@
   @include mdc-helpers.disable-mdc-fallback-declarations {
     @include mdc-checkbox.static-styles(
       $query: mdc-helpers.$mdc-base-styles-without-animation-query);
+    @include mdc-radio.static-styles(
+      $query: mdc-helpers.$mdc-base-styles-without-animation-query);
 
     &:not(._mat-animation-noopable) {
       @include mdc-checkbox.static-styles($query: animation);
+      @include mdc-radio.static-styles($query: animation);
     }
   }
 
-  // We can't use the MDC checkbox here directly, because this checkbox is purely
-  // decorative and including the MDC one will bring in unnecessary JS.
-  .mdc-checkbox {
-    $config: map.merge(checkbox-private.$private-checkbox-theme-config, (
-      // Since this checkbox isn't interactive, we can exclude the focus/hover/press styles.
+  $without-ripple-config: (
+      // Since this checkbox/radio isn't interactive, we can exclude the focus/hover/press styles.
       selected-focus-icon-color: null,
       selected-hover-icon-color: null,
       selected-pressed-icon-color: null,
       unselected-focus-icon-color: null,
       unselected-hover-icon-color: null,
       unselected-pressed-icon-color: null,
-    ));
+  );
+
+  // We can't use the MDC checkbox here directly, because this checkbox is purely
+  // decorative and including the MDC one will bring in unnecessary JS.
+  .mdc-checkbox {
+    $config: map.merge(checkbox-private.$private-checkbox-theme-config, $without-ripple-config);
 
     // MDC theme styles also include structural styles so we have to include the theme at least
     // once here. The values will be overwritten by our own theme file afterwards.
     @include mdc-checkbox-theme.theme-styles($config);
   }
 
+  .mdc-radio {
+    $config: map.merge(radio-private.$private-radio-theme-config, $without-ripple-config);
+
+    // MDC theme styles also include structural styles so we have to include the theme at least
+    // once here. The values will be overwritten by our own theme file afterwards.
+    @include mdc-radio-theme.theme-styles($config);
+  }
+
+
   // The internal checkbox is purely decorative, but because it's an `input`, the user can still
   // focus it by tabbing or clicking. Furthermore, `mat-list-option` has the `option` role which
   // doesn't allow a nested `input`. We use `display: none` both to remove it from the tab order
@@ -50,6 +67,9 @@
   .mdc-checkbox__native-control {
     display: none;
   }
+  .mdc-radio__native-control {
+    display: none;
+  }
 }
 
 .mat-mdc-list-option.mdc-list-item--selected {

src/material/list/list-option.ts

@@ -30,7 +30,12 @@ import {
 } from '@angular/core';
 import {MAT_RIPPLE_GLOBAL_OPTIONS, RippleGlobalOptions, ThemePalette} from '@angular/material/core';
 import {MatListBase, MatListItemBase} from './list-base';
-import {LIST_OPTION, ListOption, MatListOptionCheckboxPosition} from './list-option-types';
+import {
+  LIST_OPTION,
+  ListOption,
+  MatListOptionTogglePosition,
+  MatListOptionCheckboxPosition,
+} from './list-option-types';
 import {MatListItemLine, MatListItemTitle} from './list-item-sections';
 import {Platform} from '@angular/cdk/platform';
 
@@ -66,7 +71,7 @@ export interface SelectionList extends MatListBase {
     'role': 'option',
     // As per MDC, only list items in single selection mode should receive the `--selected`
     // class. For multi selection, the checkbox is used as indicator.
-    '[class.mdc-list-item--selected]': 'selected && !_selectionList.multiple',
+    '[class.mdc-list-item--selected]': 'selected',
     // Based on the checkbox position and whether there are icons or avatars, we apply MDC's
     // list-item `--leading` and `--trailing` classes.
     '[class.mdc-list-item--with-leading-avatar]': '_hasProjected("avatars", "before")',
@@ -77,6 +82,8 @@ export interface SelectionList extends MatListBase {
     // which ensure that the checkbox is positioned correctly within the list item.
     '[class.mdc-list-item--with-leading-checkbox]': '_hasCheckboxAt("before")',
     '[class.mdc-list-item--with-trailing-checkbox]': '_hasCheckboxAt("after")',
+    '[class.mdc-list-item--with-leading-radio]': '_hasRadioAt("before")',
+    '[class.mdc-list-item--with-trailing-radio]': '_hasRadioAt("after")',
     '[class.mat-accent]': 'color !== "primary" && color !== "warn"',
     '[class.mat-warn]': 'color === "warn"',
     '[class._mat-animation-noopable]': '_noopAnimations',
@@ -105,8 +112,21 @@ export class MatListOption extends MatListItemBase implements ListOption, OnInit
   @Output()
   readonly selectedChange: EventEmitter<boolean> = new EventEmitter<boolean>();
 
-  /** Whether the label should appear before or after the checkbox. Defaults to 'after' */
-  @Input() checkboxPosition: MatListOptionCheckboxPosition = 'after';
+  /** Whether the label should appear before or after the checkbox/radio. Defaults to 'after' */
+  @Input() togglePosition: MatListOptionTogglePosition = 'after';
+
+  /**
+   * Whether the label should appear before or after the checkbox/radio. Defaults to 'after'
+   *
+   * @deprecated Use `togglePosition` instead.
+   * @breaking-change 17.0.0
+   */
+  @Input() get checkboxPosition(): MatListOptionCheckboxPosition {
+    return this.togglePosition;
+  }
+  set checkboxPosition(value: MatListOptionCheckboxPosition) {
+    this.togglePosition = value;
+  }
 
   /** Theme color of the list option. This sets the color of the checkbox. */
   @Input()
@@ -225,8 +245,13 @@ export class MatListOption extends MatListItemBase implements ListOption, OnInit
   }
 
   /** Whether a checkbox is shown at the given position. */
-  _hasCheckboxAt(position: MatListOptionCheckboxPosition): boolean {
-    return this._selectionList.multiple && this._getCheckboxPosition() === position;
+  _hasCheckboxAt(position: MatListOptionTogglePosition): boolean {
+    return this._selectionList.multiple && this._getTogglePosition() === position;
+  }
+
+  /** Where a radio indicator is shown at the given position. */
+  _hasRadioAt(position: MatListOptionTogglePosition): boolean {
+    return !this._selectionList.multiple && this._getTogglePosition() === position;
   }
 
   /** Whether icons or avatars are shown at the given position. */
@@ -239,7 +264,7 @@ export class MatListOption extends MatListItemBase implements ListOption, OnInit
     // If the checkbox is shown at the specified position, neither icons or
     // avatars can be shown at the position.
     return (
-      this._getCheckboxPosition() !== position &&
+      this._getTogglePosition() !== position &&
       (type === 'avatars' ? this._avatars.length !== 0 : this._icons.length !== 0)
     );
   }
@@ -248,9 +273,9 @@ export class MatListOption extends MatListItemBase implements ListOption, OnInit
     this._selectionList._onTouched();
   }
 
-  /** Gets the current position of the checkbox. */
-  _getCheckboxPosition() {
-    return this.checkboxPosition || 'after';
+  /** Gets the current position of the checkbox/radio. */
+  _getTogglePosition() {
+    return this.togglePosition || 'after';
   }
 
   /**