feat(cdk/a11y): add high-contrast mode detection

* Add a new `HighContrastModeDetector` service that's can detect whether
the browser is in high-contrast mode (and which variety).
* Augments `A11yModule` to use this serve to add classes to the document
body indicating the high-contrast mode
* Adds `A11yModule` to `MatCommonModule` so that this runs for all of
the material components
* Updates the `cdk-high-contrast` Sass mixin to include the new CSS
classes

Author: jelbourn

src/cdk/a11y/_a11y.scss

@@ -28,4 +28,10 @@
   @media (-ms-high-contrast: $target) {
     @content;
   }
+
+  @at-root {
+    .cdk-high-contrast-#{$target} #{&} {
+      @content;
+    }
+  }
 }

src/cdk/a11y/a11y-module.ts

@@ -12,11 +12,17 @@ import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
 import {CdkMonitorFocus} from './focus-monitor/focus-monitor';
 import {CdkTrapFocus} from './focus-trap/focus-trap';
+import {HighContrastModeDetector} from './high-contrast-mode/high-contrast-mode-detector';
 import {CdkAriaLive} from './live-announcer/live-announcer';
 
+
 @NgModule({
   imports: [CommonModule, PlatformModule, ObserversModule],
   declarations: [CdkAriaLive, CdkTrapFocus, CdkMonitorFocus],
   exports: [CdkAriaLive, CdkTrapFocus, CdkMonitorFocus],
 })
-export class A11yModule {}
+export class A11yModule {
+  constructor(highContrastModeDetector: HighContrastModeDetector) {
+    highContrastModeDetector._applyBodyHighContrastModeCssClasses();
+  }
+}

src/cdk/a11y/high-contrast-mode/high-contrast-mode-detector.spec.ts

@@ -0,0 +1,86 @@
+import {
+  BLACK_ON_WHITE_CSS_CLASS,
+  HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS,
+  HighContrastMode,
+  HighContrastModeDetector, WHITE_ON_BLACK_CSS_CLASS,
+} from './high-contrast-mode-detector';
+import {Platform} from '@angular/cdk/platform';
+
+
+describe('HighContrastModeDetector', () => {
+  let fakePlatform: Platform;
+
+  beforeEach(() => {
+    fakePlatform = new Platform();
+  });
+
+  it('should detect NONE for non-browser platforms', () => {
+    fakePlatform.isBrowser = false;
+    const detector = new HighContrastModeDetector(fakePlatform, {});
+    expect(detector.getHighContrastMode())
+        .toBe(HighContrastMode.NONE, 'Expected high-contrast mode `NONE` on non-browser platforms');
+  });
+
+  it('should not apply any css classes for non-browser platforms', () => {
+    fakePlatform.isBrowser = false;
+    const fakeDocument = getFakeDocument('');
+    const detector = new HighContrastModeDetector(fakePlatform, fakeDocument);
+    detector._applyBodyHighContrastModeCssClasses();
+    expect(fakeDocument.body.className)
+        .toBe('', 'Expected body not to have any CSS classes in non-browser platforms');
+  });
+
+  it('should detect WHITE_ON_BLACK when backgrounds are coerced to black', () => {
+    const detector = new HighContrastModeDetector(fakePlatform, getFakeDocument('rgb(0,0,0)'));
+    expect(detector.getHighContrastMode())
+        .toBe(HighContrastMode.WHITE_ON_BLACK, 'Expected high-contrast mode `WHITE_ON_BLACK`');
+  });
+
+  it('should detect BLACK_ON_WHITE when backgrounds are coerced to white ', () => {
+    const detector = new HighContrastModeDetector(fakePlatform, getFakeDocument('rgb(1,1,1)'));
+    expect(detector.getHighContrastMode())
+        .toBe(HighContrastMode.BLACK_ON_WHITE, 'Expected high-contrast mode `BLACK_ON_WHITE`');
+  });
+
+  it('should detect NONE when backgrounds are not coerced ', () => {
+    const detector = new HighContrastModeDetector(fakePlatform, getFakeDocument('rgb(1,2,3)'));
+    expect(detector.getHighContrastMode())
+        .toBe(HighContrastMode.NONE, 'Expected high-contrast mode `NONE`');
+  });
+
+  it('should apply css classes for BLACK_ON_WHITE high-contrast mode', () => {
+    const fakeDocument = getFakeDocument('rgb(1,1,1)');
+    const detector = new HighContrastModeDetector(fakePlatform, fakeDocument);
+    detector._applyBodyHighContrastModeCssClasses();
+    expect(fakeDocument.body.classList).toContain(HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS);
+    expect(fakeDocument.body.classList).toContain(BLACK_ON_WHITE_CSS_CLASS);
+  });
+
+  it('should apply css classes for WHITE_ON_BLACK high-contrast mode', () => {
+    const fakeDocument = getFakeDocument('rgb(0,0,0)');
+    const detector = new HighContrastModeDetector(fakePlatform, fakeDocument);
+    detector._applyBodyHighContrastModeCssClasses();
+    expect(fakeDocument.body.classList).toContain(HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS);
+    expect(fakeDocument.body.classList).toContain(WHITE_ON_BLACK_CSS_CLASS);
+  });
+
+  it('should not apply any css classes when backgrounds are not coerced', () => {
+    const fakeDocument = getFakeDocument('');
+    const detector = new HighContrastModeDetector(fakePlatform, fakeDocument);
+    detector._applyBodyHighContrastModeCssClasses();
+    expect(fakeDocument.body.className)
+        .toBe('', 'Expected body not to have any CSS classes in non-browser platforms');
+  });
+});
+
+
+/** Gets a fake document that includes a fake `window.getComputedStyle` implementation. */
+function getFakeDocument(fakeComputedBackgroundColor: string) {
+  return {
+    body: document.createElement('body'),
+    createElement: (tag: string) => document.createElement(tag),
+    defaultView: {
+      getComputedStyle: () => ({backgroundColor: fakeComputedBackgroundColor}),
+    },
+  };
+}

src/cdk/a11y/high-contrast-mode/high-contrast-mode-detector.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Platform} from '@angular/cdk/platform';
+import {DOCUMENT} from '@angular/common';
+import {Inject, Injectable} from '@angular/core';
+
+
+/** Set of possible high-contrast mode backgrounds. */
+export enum HighContrastMode {
+  NONE,
+  BLACK_ON_WHITE,
+  WHITE_ON_BLACK,
+}
+
+/** CSS class applied to the document body when in black-on-white high-contrast mode. */
+export const BLACK_ON_WHITE_CSS_CLASS = 'cdk-high-contrast-black-on-white';
+
+/** CSS class applied to the document body when in white-on-black high-contrast mode. */
+export const WHITE_ON_BLACK_CSS_CLASS = 'cdk-high-contrast-white-on-black';
+
+/** CSS class applied to the document body when in high-contrast mode. */
+export const HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS = 'cdk-high-contrast-active';
+
+/**
+ * Service to determine whether the browser is currently in a high-constrast-mode environment.
+ *
+ * Microsoft Windows supports an accessibility feature called "High Contrast Mode". This mode
+ * changes the appearance of all applications, including web applications, to dramatically increase
+ * contrast.
+ */
+@Injectable({providedIn: 'root'})
+export class HighContrastModeDetector {
+  private _document: Document;
+
+  constructor(private _platfrom: Platform, @Inject(DOCUMENT) document: any) {
+    this._document = document;
+  }
+
+  /** Gets the current high-constrast-mode for the page. */
+  getHighContrastMode(): HighContrastMode {
+    if (!this._platfrom.isBrowser) {
+      return HighContrastMode.NONE;
+    }
+
+    // Create a test element with an arbitrary background-color that is neither black nor
+    // white; high-contrast mode will coerce the color to either black or white. Also ensure that
+    // appending the test element to the DOM does not affect layout by absolutely positioning it
+    const testElement = this._document.createElement('div');
+    testElement.style.backgroundColor = 'rgb(1,2,3)';
+    testElement.style.position = 'absolute';
+    this._document.body.appendChild(testElement);
+
+    // Get the computed style ofor the background color, collapsing spaces to normalize between
+    // browsers. Once we get this color, we no longer need the test element. Access the `window`
+    // via the document so we can fake it in tests.
+    const documentWindow = this._document.defaultView!;
+    const computedColor =
+        (documentWindow.getComputedStyle(testElement).backgroundColor || '').replace(/ /g, '');
+    this._document.body.removeChild(testElement);
+
+    switch (computedColor) {
+      case 'rgb(0,0,0)': return HighContrastMode.WHITE_ON_BLACK;
+      case 'rgb(1,1,1)': return HighContrastMode.BLACK_ON_WHITE;
+    }
+    return HighContrastMode.NONE;
+  }
+
+  /** Applies CSS classes indicating high-contrast mode to document body (browser-only). */
+  _applyBodyHighContrastModeCssClasses(): void {
+    if (this._platfrom.isBrowser) {
+      const body = this._document.body;
+      body.classList.remove(
+          HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS, BLACK_ON_WHITE_CSS_CLASS, WHITE_ON_BLACK_CSS_CLASS);
+
+      const mode = this.getHighContrastMode();
+      if (mode === HighContrastMode.BLACK_ON_WHITE) {
+        body.classList.add(HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS, BLACK_ON_WHITE_CSS_CLASS);
+      } else if (mode === HighContrastMode.WHITE_ON_BLACK) {
+        body.classList.add(HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS, WHITE_ON_BLACK_CSS_CLASS);
+      }
+    }
+  }
+}

src/cdk/a11y/public-api.ts

@@ -16,3 +16,7 @@ export * from './live-announcer/live-announcer-tokens';
 export * from './focus-monitor/focus-monitor';
 export * from './fake-mousedown';
 export * from './a11y-module';
+export {
+  HighContrastModeDetector,
+  HighContrastMode,
+}from './high-contrast-mode/high-contrast-mode-detector';

src/material/core/common-behaviors/common-module.ts

@@ -6,9 +6,10 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {NgModule, InjectionToken, Optional, Inject, isDevMode, Version} from '@angular/core';
-import {BidiModule} from '@angular/cdk/bidi';
 import {VERSION as CDK_VERSION} from '@angular/cdk';
+import {A11yModule} from '@angular/cdk/a11y';
+import {BidiModule} from '@angular/cdk/bidi';
+import {Inject, InjectionToken, isDevMode, NgModule, Optional, Version} from '@angular/core';
 
 // Private version constant to circumvent test/build issues,
 // i.e. avoid core to depend on the @angular/material primary entry-point
@@ -53,7 +54,7 @@ export interface GranularSanityChecks {
  * This module should be imported to each top-level component module (e.g., MatTabsModule).
  */
 @NgModule({
-  imports: [BidiModule],
+  imports: [A11yModule, BidiModule],
   exports: [BidiModule],
 })
 export class MatCommonModule {