feat(toc): add table of contents to overview and guides

Author: amcdnl

src/_app-theme.scss

@@ -9,6 +9,7 @@
 @import './app/shared/example-viewer/example-viewer-theme';
 @import './app/shared/footer/footer-theme';
 @import './app/shared/navbar/navbar-theme';
+@import './app/shared/table-of-contents/table-of-contents-theme';
 @import './styles/api-theme';
 @import './styles/markdown-theme';
 @import './styles/svg-theme';
@@ -53,4 +54,5 @@
   @include guide-list-theme($theme);
   @include home-page-theme($theme);
   @include nav-bar-theme($theme);
+  @include table-of-contents-theme($theme);
 }

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

@@ -1,3 +1,7 @@
 <doc-viewer
     documentUrl="/assets/documents/overview/{{componentViewer.componentDocItem.id}}.html"
-    class="docs-component-view-text-content"></doc-viewer>
+    class="docs-component-view-text-content component-overview">
+</doc-viewer>
+<table-of-contents
+  container=".mat-sidenav-content">
+</table-of-contents>

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

@@ -14,7 +14,32 @@ app-component-viewer {
 }
 
 .docs-component-viewer-content {
+  position: relative;
   min-height: 500px;
+
+  table-of-contents {
+    display: inline-flex;
+    top: 35px;
+
+    @media (max-width: $small-breakpoint-width) {
+      display: none;
+    }
+  }
+}
+
+.docs-component-view-text-content {
+  display: inline-flex;
+  flex-grow: 1;
+}
+
+.component-overview {
+  width: 80%;
+  margin-right: 20px;
+
+  @media (max-width: $small-breakpoint-width) {
+    width: 100%;
+    margin-right: 0;
+  }
 }
 
 .docs-example-source {

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

@@ -14,6 +14,9 @@ const exampleKey = 'button-types';
 
 const mockActivatedRoute = {
   snapshot: {},
+  fragment: Observable.create(observer => {
+    observer.complete();
+  }),
   params: Observable.create(observer => {
     observer.next({id: docItemsId});
     observer.complete();

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

@@ -5,7 +5,8 @@ import {ComponentPageTitle} from '../page-title/page-title';
 import {MdTabsModule} from '@angular/material';
 import {DocViewerModule} from '../../shared/doc-viewer/doc-viewer-module';
 import {CommonModule} from '@angular/common';
-
+import {HeaderLinkModule} from '../../shared/header-link/header-link.module';
+import {TableOfContentsModule} from '../../shared/table-of-contents/table-of-contents.module';
 
 @Component({
   selector: 'app-component-viewer',
@@ -49,10 +50,15 @@ export class ComponentApi extends ComponentOverview {}
 })
 export class ComponentExamples extends ComponentOverview {}
 
-
-
 @NgModule({
-  imports: [MdTabsModule, RouterModule, DocViewerModule, CommonModule],
+  imports: [
+    MdTabsModule,
+    RouterModule,
+    DocViewerModule,
+    CommonModule,
+    HeaderLinkModule,
+    TableOfContentsModule
+  ],
   exports: [ComponentViewer],
   declarations: [ComponentViewer, ComponentOverview, ComponentApi, ComponentExamples],
   providers: [DocumentationItems, ComponentPageTitle],

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

@@ -2,6 +2,9 @@
   <h1>{{guide.name}}</h1>
 </div>
 
-<doc-viewer class="docs-guide-content" [documentUrl]="guide.document"></doc-viewer>
+<div class="docs-guide-content">
+  <doc-viewer class="docs-guide-viewer" [documentUrl]="guide.document"></doc-viewer>
+  <table-of-contents></table-of-contents>
+</div>
 
 <app-footer></app-footer>

src/app/pages/guide-viewer/guide-viewer.scss

@@ -1,4 +1,5 @@
 @import "../../../../node_modules/@angular/material/theming";
+@import '../../../styles/constants';
 
 /* For desktop, the content should be aligned with the page title. */
 $guide-content-margin-side: 70px;
@@ -20,3 +21,22 @@ $guide-content-margin-side-xs: 15px;
     margin-right: $guide-content-margin-side-xs;
   }
 }
+
+.docs-guide-viewer {
+  width: 80%;
+  display: block;
+  float: left;
+
+  @media (max-width: $small-breakpoint-width) {
+    width: 100%;
+  }
+}
+
+table-of-contents {
+  float: right;
+  top: 35px;
+
+  @media (max-width: $small-breakpoint-width) {
+    display: none;
+  }
+}

src/app/pages/guide-viewer/guide-viewer.spec.ts

@@ -7,6 +7,9 @@ import {DocsAppTestingModule} from '../../testing/testing-module';
 const guideItemsId = 'getting-started';
 
 const mockActivatedRoute = {
+  fragment: Observable.create(observer => {
+    observer.complete();
+  }),
   params: Observable.create(observer => {
     observer.next({id: guideItemsId});
     observer.complete();

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

@@ -3,7 +3,8 @@ import {ActivatedRoute, RouterModule} from '@angular/router';
 import {GuideItem, GuideItems} from '../../shared/guide-items/guide-items';
 import {FooterModule} from '../../shared/footer/footer';
 import {DocViewerModule} from '../../shared/doc-viewer/doc-viewer-module';
-
+import {HeaderLinkModule} from '../../shared/header-link/header-link.module';
+import {TableOfContentsModule} from '../../shared/table-of-contents/table-of-contents.module';
 
 @Component({
   selector: 'guide-viewer',
@@ -21,7 +22,7 @@ export class GuideViewer {
 }
 
 @NgModule({
-  imports: [DocViewerModule, FooterModule, RouterModule],
+  imports: [DocViewerModule, FooterModule, RouterModule, HeaderLinkModule, TableOfContentsModule],
   exports: [GuideViewer],
   declarations: [GuideViewer],
   providers: [GuideItems],

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

@@ -11,7 +11,7 @@ import {
 import {Http} from '@angular/http';
 import {ComponentPortal, DomPortalHost} from '@angular/material';
 import {ExampleViewer} from '../example-viewer/example-viewer';
-
+import {HeaderLink} from '../header-link/header-link';
 
 @Component({
   selector: 'doc-viewer',
@@ -41,7 +41,8 @@ export class DocViewer implements OnDestroy {
           if (response.ok) {
             let docHtml = response.text();
             this._elementRef.nativeElement.innerHTML = docHtml;
-            this._loadLiveExamples();
+            this._loadComponents('material-docs-example', ExampleViewer);
+            this._loadComponents('header-link', HeaderLink);
           } else {
             this._elementRef.nativeElement.innerText =
               `Failed to load document: ${url}. Error: ${response.status}`;
@@ -58,22 +59,24 @@ export class DocViewer implements OnDestroy {
     // the wrong place in the DOM after switching tabs. This function is a workaround to
     // put the live examples back in the right place.
     this._clearLiveExamples();
-    this._loadLiveExamples();
+    this._loadComponents('material-docs-example', ExampleViewer);
+    this._loadComponents('header-link', HeaderLink);
   }
 
   /** Instantiate a ExampleViewer for each example. */
-  private _loadLiveExamples() {
+  private _loadComponents(componentName: string, componentClass: any) {
     let exampleElements =
-        this._elementRef.nativeElement.querySelectorAll('[material-docs-example]');
+        this._elementRef.nativeElement.querySelectorAll(`[${componentName}]`);
+
     Array.prototype.slice.call(exampleElements).forEach((element: Element) => {
-      let example = element.getAttribute('material-docs-example');
+      let example = element.getAttribute(componentName);
 
       let exampleContainer = document.createElement('div');
       element.appendChild(exampleContainer);
 
       let portalHost = new DomPortalHost(
           exampleContainer, this._componentFactoryResolver, this._appRef, this._injector);
-      let examplePortal = new ComponentPortal(ExampleViewer, this._viewContainerRef);
+      let examplePortal = new ComponentPortal(componentClass, this._viewContainerRef);
       let exampleViewer = portalHost.attach(examplePortal);
       exampleViewer.instance.example = example;
 

src/app/shared/header-link/header-link.module.ts

@@ -0,0 +1,12 @@
+import {CommonModule} from '@angular/common';
+import {NgModule} from '@angular/core';
+import {HeaderLink} from './header-link';
+import {RouterModule} from '@angular/router';
+
+@NgModule({
+  imports: [CommonModule, RouterModule],
+  declarations: [HeaderLink],
+  exports: [HeaderLink],
+  entryComponents: [HeaderLink],
+})
+export class HeaderLinkModule { }

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

@@ -0,0 +1,30 @@
+import {Component, Input} from '@angular/core';
+import {Router} from '@angular/router';
+
+@Component({
+  selector: 'header-link',
+  template: `
+    <a
+      title="Link to this heading"
+      class="header-link docs-markdown-a"
+      aria-hidden="true"
+      [href]="url">
+      <i class="material-icons">link</i>
+    </a>
+  `
+})
+export class HeaderLink {
+
+  @Input() example: string;
+
+  get url(): string {
+    return `${this._rootUrl}#${this.example}`;
+  }
+
+  private _rootUrl: string;
+
+  constructor(router: Router) {
+    this._rootUrl = router.url.split('#')[0];
+  }
+
+}

src/app/shared/plunker/plunker-button.ts

@@ -18,7 +18,7 @@ export class PlunkerButton {
    * The form creation usually happens extremely quickly, but we handle the case of the
    * plunker not yet being ready for people will poor network connections or slow devices.
    */
-  isDisabled: boolean = false;
+  isDisabled = false;
   plunkerForm: HTMLFormElement;
 
   @Input()

src/app/shared/table-of-contents/_table-of-contents-theme.scss

@@ -0,0 +1,20 @@
+@mixin table-of-contents-theme($theme) {
+  $primary: map-get($theme, primary);
+  $accent: map-get($theme, accent);
+  $warn: map-get($theme, warn);
+  $background: map-get($theme, background);
+  $foreground: map-get($theme, foreground);
+
+  .toc-container {
+    border-left: solid 4px mat-color($primary);
+  }
+
+  a {
+    color: mat-color($foreground, secondary-text);
+
+    &:hover,
+    &.active {
+      color: mat-color($primary);
+    }
+  }
+}

src/app/shared/table-of-contents/table-of-contents.module.ts

@@ -0,0 +1,12 @@
+import {CommonModule} from '@angular/common';
+import {NgModule} from '@angular/core';
+import {TableOfContents} from './table-of-contents';
+import {RouterModule} from '@angular/router';
+
+@NgModule({
+  imports: [CommonModule, RouterModule],
+  declarations: [TableOfContents],
+  exports: [TableOfContents],
+  entryComponents: [TableOfContents],
+})
+export class TableOfContentsModule { }

src/app/shared/table-of-contents/table-of-contents.scss

@@ -0,0 +1,37 @@
+:host {
+  font-size: 13px;
+  width: 15%;
+  position: sticky;
+  top: 0;
+}
+
+.toc-container {
+  padding: 5px 0 10px 12px;
+}
+
+h2 {
+  margin: 0;
+  padding: 0;
+  font-size: 13px;
+  font-weight: bold;
+}
+
+ul, li {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+li {
+  line-height: 16px;
+  margin: 8px 0 0;
+  position: relative;
+}
+
+a {
+  text-decoration: none;
+}
+
+.li-h4 {
+  margin-left: 12px;
+}

src/app/shared/table-of-contents/table-of-contents.spec.ts

@@ -0,0 +1,50 @@
+import {async, ComponentFixture, TestBed} from '@angular/core/testing';
+import {Observable} from 'rxjs/Observable';
+import {ActivatedRoute} from '@angular/router';
+import {TableOfContents} from './table-of-contents';
+import {TableOfContentsModule} from './table-of-contents.module';
+import {DocsAppTestingModule} from '../../testing/testing-module';
+
+const mockActivatedRoute = {
+  fragment: Observable.create(observer => {
+    observer.complete();
+  })
+};
+
+describe('TableOfContents', () => {
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      imports: [TableOfContentsModule, DocsAppTestingModule],
+      providers: [
+        {provide: ActivatedRoute, useValue: mockActivatedRoute},
+      ]
+    }).compileComponents();
+  }));
+
+  let fixture: ComponentFixture<TableOfContents>;
+  let component: TableOfContents;
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(TableOfContents);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should have no header', () => {
+    const header = fixture
+      .nativeElement
+      .querySelector('h2');
+    expect(header).toBeNull();
+  });
+
+  it('should have header and links', () => {
+    component.links = [{ type: 'h2', id: 'test', name: 'test'}];
+
+    const header = fixture.nativeElement.querySelector('h2');
+    expect(header).toBeDefined();
+
+    const links = fixture.nativeElement.querySelector('li');
+    expect(links).toBeDefined();
+  });
+});