feat(material/list): introduce type for checkbox position

In order to provide a better way to type the checkbox position
of a list option, we now provide an exported type that can be
used instead of manually repeating `'before' | 'after'` in projects
setting the checkbox position through a class member for example.

This also allows us to improve type safety in the test harnesses.

Author: devversion

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

@@ -7,6 +7,7 @@
  */
 
 import {Component} from '@angular/core';
+import {MatListOptionCheckboxPosition} from '@angular/material/list';
 
 
 @Component({
@@ -27,7 +28,7 @@ export class ListDemo {
     {name: 'Bobby', headline: 'UX designer'}
   ];
 
-  checkboxPosition: 'before'|'after' = 'before';
+  checkboxPosition: MatListOptionCheckboxPosition = 'before';
 
   messages: {from: string, subject: string, message: string, image: string}[] = [
     {

src/material-experimental/mdc-list/list-styling.ts

@@ -10,8 +10,10 @@ import {Directive, Inject, Optional} from '@angular/core';
 import {LIST_OPTION, ListOption} from './list-option-types';
 
 /**
- * Directive whose purpose is to add the MDC list-item `graphic` or `meta`
- * class depending on checkbox position in list options.
+ * MDC uses the very intuitively named classes `.mdc-list-item__graphic` and `.mat-list-item__meta`
+ * to position content such as icons or checkboxes that comes either before or after the text
+ * content respectively. This directive detects the placement of the checkbox and applies the
+ * correct MDC class to position the icon/avatar on the opposite side.
  * @docs-private
  */
 @Directive({

src/material-experimental/mdc-list/list.scss

@@ -54,10 +54,10 @@
   height: $size;
   border-radius: 50%;
 
-  // If the avatar is displayed in the graphic section of a list-item (i.e. at the start),
-  // we override the default "graphic" horizontal spacing that is designed for icons, to
-  // work for actual avatar images. The avatar by default is used within the `graphic` section,
-  // but could be also outside in case of a selection-list option with a checkbox at start.
+  // Avatars that come before the text have the .mdc-list-item__graphic class.
+  // MDC's .mdc-list--avatar-list class would normally apply overrides to set the appropriate
+  // margins for avatar images, but since ours is a per-list-item setting we need to add similar
+  // styles ourselves.
   &.mdc-list-item__graphic {
     margin-left: 0;
     margin-right: $margin-value;

src/material/list/selection-list.ts

@@ -82,6 +82,12 @@ export class MatSelectionListChange {
     public options: MatListOption[]) {}
 }
 
+/**
+ * Type describing possible positions of a checkbox in a list option
+ * with respect to the list item's text.
+ */
+export type MatListOptionCheckboxPosition = 'before'|'after';
+
 /**
  * Component for list-options of selection-list. Each list-option can automatically
  * generate a checkbox and can put current item into the selectionModel of selection-list
@@ -131,7 +137,7 @@ export class MatListOption extends _MatListOptionMixinBase implements AfterConte
   @ViewChild('text') _text: ElementRef;
 
   /** Whether the label should appear before or after the checkbox. Defaults to 'after' */
-  @Input() checkboxPosition: 'before' | 'after' = 'after';
+  @Input() checkboxPosition: MatListOptionCheckboxPosition = 'after';
 
   /** Theme color of the list option. This sets the color of the checkbox. */
   @Input()

src/material/list/testing/BUILD.bazel

@@ -13,6 +13,7 @@ ts_library(
         "//src/cdk/coercion",
         "//src/cdk/testing",
         "//src/material/divider/testing",
+        "//src/material/list",
     ],
 )
 

src/material/list/testing/list-item-harness-base.ts

@@ -53,6 +53,7 @@ export class MatSubheaderHarness extends ComponentHarness {
 /** Selectors for the various list item sections that may contain user content. */
 export const enum MatListItemSection {
   CONTENT = '.mat-list-item-content'
+  // TODO(mmalerba): consider adding sections for leading/trailing icons.
 }
 
 /**

src/material/list/testing/selection-list-harness.ts

@@ -7,6 +7,7 @@
  */
 
 import {HarnessPredicate} from '@angular/cdk/testing';
+import {MatListOptionCheckboxPosition} from '@angular/material/list';
 import {MatListHarnessBase} from './list-harness-base';
 import {
   ListItemHarnessFilters,
@@ -88,7 +89,7 @@ export class MatListOptionHarness extends MatListItemHarnessBase {
   private _itemContent = this.locatorFor('.mat-list-item-content');
 
   /** Gets the position of the checkbox relative to the list option content. */
-  async getCheckboxPosition(): Promise<'before' | 'after'> {
+  async getCheckboxPosition(): Promise<MatListOptionCheckboxPosition> {
     return await (await this._itemContent()).hasClass('mat-list-item-content-reverse') ?
         'after' : 'before';
   }

tools/public_api_guard/material/list.d.ts

@@ -53,7 +53,7 @@ export declare class MatListOption extends _MatListOptionMixinBase implements Af
     _icon: MatListIconCssMatStyler;
     _lines: QueryList<MatLine>;
     _text: ElementRef;
-    checkboxPosition: 'before' | 'after';
+    checkboxPosition: MatListOptionCheckboxPosition;
     get color(): ThemePalette;
     set color(newValue: ThemePalette);
     get disabled(): any;
@@ -85,6 +85,8 @@ export declare class MatListOption extends _MatListOptionMixinBase implements Af
     static ɵfac: i0.ɵɵFactoryDef<MatListOption, never>;
 }
 
+export declare type MatListOptionCheckboxPosition = 'before' | 'after';
+
 export declare class MatListSubheaderCssMatStyler {
     static ɵdir: i0.ɵɵDirectiveDefWithMeta<MatListSubheaderCssMatStyler, "[mat-subheader], [matSubheader]", never, {}, {}, never>;
     static ɵfac: i0.ɵɵFactoryDef<MatListSubheaderCssMatStyler, never>;

tools/public_api_guard/material/list/testing.d.ts

@@ -52,7 +52,7 @@ export declare class MatListOptionHarness extends MatListItemHarnessBase {
     blur(): Promise<void>;
     deselect(): Promise<void>;
     focus(): Promise<void>;
-    getCheckboxPosition(): Promise<'before' | 'after'>;
+    getCheckboxPosition(): Promise<MatListOptionCheckboxPosition>;
     isDisabled(): Promise<boolean>;
     isFocused(): Promise<boolean>;
     isSelected(): Promise<boolean>;