docs-infra: address numerous a11y issues

e2e/src/app.e2e-spec.ts

@@ -8,7 +8,7 @@ describe('Material Docs App', () => {
     page = new MaterialDocsAppPage();
   });
 
-  it('should display welcome message', async() => {
+  it('should display welcome message', async () => {
     await page.navigateTo();
     expect(await page.getTitleText()).toEqual('Angular Material');
   });

package.json

@@ -8,7 +8,7 @@
     "start": "yarn build-themes && ng serve",
     "start:jit": "yarn build-themes && ng serve --aot=false",
     "start:prod": "yarn build-themes && ng serve --prod",
-    "lint": "tslint -p tsconfig.json",
+    "lint": "ng lint",
     "test": "yarn build-themes && ng test",
     "pree2e": "webdriver-manager update",
     "e2e": "yarn build-themes && ng e2e",

src/app/material-docs-app.html

@@ -1,3 +1,2 @@
 <app-navbar class="mat-elevation-z6"></app-navbar>
 <router-outlet></router-outlet>
-

src/app/pages/component-page-header/component-page-header.html

@@ -1,7 +1,7 @@
-<div class="docs-primary-header component-page-header">
+<header class="docs-primary-header component-page-header">
   <button mat-button class="sidenav-toggle" (click)="toggleSidenav.emit()">
     <mat-icon>menu</mat-icon>
   </button>
 
   <h1 focusOnNavigation>{{getTitle()}} </h1>
-</div>
+</header>

src/app/pages/component-sidenav/_component-sidenav-theme.scss

@@ -17,7 +17,8 @@
     }
 
     .docs-nav-content-btn {
-      color: rgba(mat-color($foreground, text), .5);
+      color: rgba(mat-color($foreground, text), 0.7);
+      font-family: Roboto, "Helvetica Neue", sans-serif;
 
       &:focus {
         // override the default background
@@ -37,6 +38,10 @@
       &:hover {
         color: mat-color($primary, if($is-dark-theme, 200, default));
       }
+
+      &.docs-component-viewer-sidenav-item-selected {
+        background: rgba(0, 0, 0, $nav-background-focus-opacity);
+      }
     }
   }
 

src/app/pages/component-sidenav/component-nav.html

@@ -1,23 +1,23 @@
 <div class="docs-component-viewer-nav">
   <div class="docs-component-viewer-nav-content">
-    <nav *ngFor="let category of docItems.getCategories((params | async)?.section); let last = last;">
+    <div *ngFor="let category of docItems.getCategories((params | async)?.section); let last = last;">
       <button cdkAccordionItem #panel="cdkAccordionItem" (click)="panel.toggle()" expanded="true"
               class="docs-nav-content-btn"
-              [attr.aria-label]="category.name + ', section toggle'"
               [attr.aria-controls]="'panel-' + category.id"
               [attr.aria-expanded]="panel.expanded">
         {{category.name}}
         <mat-icon>{{panel.expanded ? 'keyboard_arrow_up' :  'keyboard_arrow_down'}}</mat-icon>
       </button>
-      <ul [@bodyExpansion]="panel.expanded ? 'expanded' : 'collapsed'" id="panel-{{category.id}}">
-        <li *ngFor="let component of category.items">
-          <a [routerLink]="'/' + (params | async)?.section+ '/' + component.id"
-            routerLinkActive="docs-component-viewer-sidenav-item-selected">
-            {{component.name}}
-          </a>
-        </li>
-      </ul>
+      <mat-nav-list dense [@bodyExpansion]="panel.expanded ? 'expanded' : 'collapsed'"
+                    id="panel-{{category.id}}" [attr.aria-label]="category.name">
+        <a mat-list-item *ngFor="let component of category.items"
+           [routerLink]="'/' + (params | async)?.section+ '/' + component.id"
+           routerLinkActive="docs-component-viewer-sidenav-item-selected"
+           [attr.aria-current]="currentItemId === component.id ? 'page': 'false'">
+          {{component.name}}
+        </a>
+      </mat-nav-list>
       <hr *ngIf="!last" />
-    </nav>
+    </div>
   </div>
 </div>

src/app/pages/component-sidenav/component-sidenav.html

@@ -2,23 +2,23 @@
   <!-- If on small screen, menu resides in drawer -->
   <mat-sidenav #sidenav class="docs-component-viewer-sidenav"
               *ngIf="(isScreenSmall | async)"
-              [opened]="!(isScreenSmall | async)"
+              [opened]="(isScreenSmall | async) === false"
               [mode]="(isScreenSmall | async) ? 'over' : 'side'"
-              [fixedInViewport]="(isScreenSmall | async) ? true : false"
+              [fixedInViewport]="(isScreenSmall | async)"
               [fixedTopGap]="92">
     <app-component-nav [params]="params"></app-component-nav>
   </mat-sidenav>
   <div class="docs-component-sidenav-content">
     <component-page-header (toggleSidenav)="sidenav.toggle()"></component-page-header>
     <div class="docs-component-sidenav-inner-content">
-      <div class="docs-component-sidenav-body-content">
+      <main class="docs-component-sidenav-body-content">
         <!-- If on large screen, menu resides to left of content -->
         <app-component-nav
-          *ngIf="!(isScreenSmall | async)"
+          *ngIf="(isScreenSmall | async) === false"
           [params]="params">
         </app-component-nav>
         <router-outlet></router-outlet>
-      </div>
+      </main>
       <app-footer></app-footer>
     </div>
   </div>

src/app/pages/component-sidenav/component-sidenav.ts

@@ -37,6 +37,7 @@ import {HttpClientModule} from '@angular/common/http';
 import {StackBlitzButtonModule} from '../../shared/stack-blitz';
 import {SvgViewerModule} from '../../shared/svg-viewer/svg-viewer';
 import {ExampleModule} from '@angular/components-examples';
+import {MatListModule} from '@angular/material/list';
 
 const SMALL_WIDTH_BREAKPOINT = 720;
 
@@ -81,6 +82,7 @@ export class ComponentSidenav implements OnInit {
 export class ComponentNav implements OnInit, OnDestroy {
   @Input() params: Observable<Params>;
   expansions: {[key: string]: boolean} = {};
+  currentItemId: string;
   private _onDestroy = new Subject<void>();
 
   constructor(public docItems: DocumentationItems,
@@ -91,7 +93,7 @@ export class ComponentNav implements OnInit, OnDestroy {
       startWith(null),
       switchMap(() => this.params),
       takeUntil(this._onDestroy)
-    ).subscribe(p => this.setExpansions(p));
+    ).subscribe(params => this.setExpansions(params));
   }
 
   ngOnDestroy() {
@@ -103,14 +105,12 @@ export class ComponentNav implements OnInit, OnDestroy {
   setExpansions(params: Params) {
     const categories = this.docItems.getCategories(params.section);
     for (const category of (categories || [])) {
-      if (this.expansions[category.id]) {
-        continue;
-      }
 
       let match = false;
       for (const item of category.items) {
         if (this._router.url.indexOf(item.id) > -1) {
           match = true;
+          this.currentItemId = item.id;
           break;
         }
       }
@@ -167,6 +167,9 @@ const routes: Routes = [ {
 
 @NgModule({
   imports: [
+    MatSidenavModule,
+    MatListModule,
+    RouterModule,
     CommonModule,
     ComponentCategoryListModule,
     ComponentHeaderModule,

src/app/pages/component-viewer/component-overview.html

@@ -1,7 +1,7 @@
 <ng-container *ngIf="componentViewer.componentDocItem | async; let docItem">
-  <span class="cdk-visually-hidden" tabindex="-1" #initialFocusTarget>
+  <h2 class="cdk-visually-hidden" tabindex="-1" #initialFocusTarget>
     Overview for {{docItem?.id}}
-  </span>
+  </h2>
   <doc-viewer
       documentUrl="/docs-content/overviews/{{docItem?.packageName}}/{{docItem?.id}}.html"
       class="docs-component-view-text-content docs-component-overview"

src/app/pages/component-viewer/component-viewer.html

@@ -1,5 +1,6 @@
 <div class="docs-component-viewer">
-  <nav mat-tab-nav-bar class="docs-component-viewer-tabbed-content">
+  <nav mat-tab-nav-bar class="docs-component-viewer-tabbed-content"
+       aria-label="Documentation Sections">
     <a mat-tab-link class="docs-component-viewer-section-tab"
         *ngFor="let section of sections"
         [routerLink]="section.toLowerCase()"

src/app/pages/component-viewer/component-viewer.ts

@@ -36,7 +36,7 @@ export class ComponentViewer implements OnDestroy {
               public _componentPageTitle: ComponentPageTitle,
               public docItems: DocumentationItems,
               ) {
-    let routeAndParentParams = [_route.params];
+    const routeAndParentParams = [_route.params];
     if (_route.parent) {
       routeAndParentParams.push(_route.parent.params);
     }

src/app/pages/guide-list/guide-list.html

@@ -1,13 +1,15 @@
-<div class="docs-primary-header">
+<header class="docs-primary-header">
   <h1>Guides</h1>
-</div>
+</header>
 
-<mat-nav-list class="docs-guide-list">
-  <a mat-list-item *ngFor="let guide of guideItems.getAllItems()"
-      class="docs-guide-item"
-      [routerLink]="['/guide/', guide.id]">
-    {{guide.name}}
-  </a>
-</mat-nav-list>
+<main>
+  <mat-nav-list class="docs-guide-list">
+    <a mat-list-item *ngFor="let guide of guideItems.getAllItems()"
+        class="docs-guide-item"
+        [routerLink]="['/guide/', guide.id]">
+      {{guide.name}}
+    </a>
+  </mat-nav-list>
+</main>
 
 <app-footer></app-footer>

src/app/pages/homepage/homepage.html

@@ -11,7 +11,7 @@ <h2> Material Design components for Angular</h2>
   </div>
 </header>
 
-<div class="docs-homepage-promo">
+<main class="docs-homepage-promo">
   <div class="docs-homepage-row">
     <div class="docs-homepage-promo-img">
       <docs-svg-viewer src="../assets/img/homepage/sprintzerotoapp.svg"
@@ -60,6 +60,6 @@ <h2>Optimized for Angular</h2>
       Get started
     </a>
   </div>
-</div>
+</main>
 
 <app-footer></app-footer>

src/app/shared/doc-viewer/doc-viewer.spec.ts

@@ -22,38 +22,37 @@ describe('DocViewer', () => {
   }));
 
   it('should load doc into innerHTML', () => {
-    let fixture = TestBed.createComponent(DocViewerTestComponent);
+    const fixture = TestBed.createComponent(DocViewerTestComponent);
     fixture.detectChanges();
 
     const url = fixture.componentInstance.documentUrl;
     http.expectOne(url).flush(FAKE_DOCS[url]);
 
-    let docViewer = fixture.debugElement.query(By.directive(DocViewer));
+    const docViewer = fixture.debugElement.query(By.directive(DocViewer));
     expect(docViewer).not.toBeNull();
     expect(docViewer.nativeElement.innerHTML).toBe('<div>my docs page</div>');
   });
 
   it('should save textContent of the doc', () => {
-    let fixture = TestBed.createComponent(DocViewerTestComponent);
+    const fixture = TestBed.createComponent(DocViewerTestComponent);
     fixture.detectChanges();
 
     const url = fixture.componentInstance.documentUrl;
     http.expectOne(url).flush(FAKE_DOCS[url]);
 
-    let docViewer = fixture.debugElement.query(By.directive(DocViewer));
+    const docViewer = fixture.debugElement.query(By.directive(DocViewer));
     expect(docViewer.componentInstance.textContent).toBe('my docs page');
   });
 
-
   it('should correct hash based links', () => {
-    let fixture = TestBed.createComponent(DocViewerTestComponent);
+    const fixture = TestBed.createComponent(DocViewerTestComponent);
     fixture.componentInstance.documentUrl = `http://material.angular.io/doc-with-links.html`;
     fixture.detectChanges();
 
     const url = fixture.componentInstance.documentUrl;
     http.expectOne(url).flush(FAKE_DOCS[url]);
 
-    let docViewer = fixture.debugElement.query(By.directive(DocViewer));
+    const docViewer = fixture.debugElement.query(By.directive(DocViewer));
     // Our test runner runs at the page /context.html, so it will be the prepended value.
     expect(docViewer.nativeElement.innerHTML).toContain(`/context.html#test"`);
   });

src/app/shared/doc-viewer/doc-viewer.ts

@@ -1,4 +1,4 @@
-import {ComponentPortal, DomPortalHost} from '@angular/cdk/portal';
+import {ComponentPortal, DomPortalOutlet} from '@angular/cdk/portal';
 import {HttpClient, HttpErrorResponse} from '@angular/common/http';
 import {DomSanitizer} from '@angular/platform-browser';
 import {
@@ -25,7 +25,7 @@ import {HeaderLink} from './header-link';
   template: 'Loading document...',
 })
 export class DocViewer implements OnDestroy {
-  private _portalHosts: DomPortalHost[] = [];
+  private _portalHosts: DomPortalOutlet[] = [];
   private _documentFetchSubscription: Subscription;
 
   @Input() name: string;
@@ -102,15 +102,15 @@ export class DocViewer implements OnDestroy {
 
   /** Instantiate a ExampleViewer for each example. */
   private _loadComponents(componentName: string, componentClass: any) {
-    let exampleElements =
+    const exampleElements =
         this._elementRef.nativeElement.querySelectorAll(`[${componentName}]`);
 
     Array.prototype.slice.call(exampleElements).forEach((element: Element) => {
-      let example = element.getAttribute(componentName);
-      let portalHost = new DomPortalHost(
+      const example = element.getAttribute(componentName);
+      const portalHost = new DomPortalOutlet(
           element, this._componentFactoryResolver, this._appRef, this._injector);
-      let examplePortal = new ComponentPortal(componentClass, this._viewContainerRef);
-      let exampleViewer = portalHost.attach(examplePortal);
+      const examplePortal = new ComponentPortal(componentClass, this._viewContainerRef);
+      const exampleViewer = portalHost.attach(examplePortal);
       if (example !== null) {
         (exampleViewer.instance as ExampleViewer).example = example;
       }

src/app/shared/doc-viewer/header-link.ts

@@ -17,12 +17,8 @@ import {Router} from '@angular/router';
 @Component({
   selector: 'header-link',
   template: `
-    <a
-      title="Link to this heading"
-      aria-label="Link to this heading"
-      class="docs-markdown-a"
-      [attr.aria-describedby]="example"
-      [href]="_getFragmentUrl()">
+    <a aria-label="Link to this heading" class="docs-markdown-a"
+      [attr.aria-describedby]="example" [href]="_getFragmentUrl()">
       <mat-icon>link</mat-icon>
     </a>
   `

src/app/shared/documentation-items/documentation-items.ts

@@ -583,14 +583,14 @@ const DOCS: {[key: string]: DocCategory[]} = {
   ]
 };
 
-for (let category of DOCS[COMPONENTS]) {
-  for (let doc of category.items) {
+for (const category of DOCS[COMPONENTS]) {
+  for (const doc of category.items) {
     doc.packageName = 'material';
   }
 }
 
-for (let category of DOCS[CDK]) {
-  for (let doc of category.items) {
+for (const category of DOCS[CDK]) {
+  for (const doc of category.items) {
     doc.packageName = 'cdk';
   }
 }
@@ -619,11 +619,11 @@ export class DocumentationItems {
   }
 
   getItemById(id: string, section: string): DocItem | undefined {
-    const sectionLookup = section == 'cdk' ? 'cdk' : 'material';
-    return ALL_DOCS.find(doc => doc.id === id && doc.packageName == sectionLookup);
+    const sectionLookup = section === 'cdk' ? 'cdk' : 'material';
+    return ALL_DOCS.find(doc => doc.id === id && doc.packageName === sectionLookup);
   }
 
   getCategoryById(id: string): DocCategory | undefined {
-    return ALL_CATEGORIES.find(c => c.id == id);
+    return ALL_CATEGORIES.find(c => c.id === id);
   }
 }

src/app/shared/example-viewer/example-viewer.html

@@ -3,7 +3,7 @@
     <div class="docs-example-viewer-title-spacer">{{exampleData?.title}}</div>
 
     <button mat-icon-button type="button" (click)="toggleSourceView()"
-            [matTooltip]="'View source'">
+            [matTooltip]="'View ' + exampleData?.title + ' source'" aria-label="View source">
       <mat-icon>
         <svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 24 24" fit="" preserveAspectRatio="xMidYMid meet" focusable="false">
           <path fill="none" d="M0 0h24v24H0V0z"></path>