aio + docs/api: API badge placement

aio/src/app/layout/doc-viewer/doc-viewer.component.spec.ts

@@ -175,6 +175,9 @@ describe('DocViewerComponent', () => {
     const DOC_WITHOUT_H1 = 'Some content';
     const DOC_WITH_H1 = '<h1>Features</h1>Some content';
     const DOC_WITH_NO_TOC_H1 = '<h1 class="no-toc">Features</h1>Some content';
+    const DOC_WITH_EMBEDDED_TOC = '<h1>Features</h1><aio-toc class="embedded"></aio-toc>Some content';
+    const DOC_WITH_EMBEDDED_TOC_WITHOUT_H1 = '<aio-toc class="embedded"></aio-toc>Some content';
+    const DOC_WITH_EMBEDDED_TOC_WITH_NO_TOC_H1 = '<aio-toc class="embedded"></aio-toc>Some content';
     const DOC_WITH_HIDDEN_H1_CONTENT = '<h1><i style="visibility: hidden">link</i>Features</h1>Some content';
     let titleService: MockTitle;
     let tocService: MockTocService;
@@ -271,27 +274,46 @@ describe('DocViewerComponent', () => {
     });
 
     describe('(ToC)', () => {
-      it('should add an embedded ToC element if there is an `<h1>` heading', () => {
-        doPrepareTitleAndToc(DOC_WITH_H1);
-        const tocEl = getTocEl()!;
+      describe('needed', () => {
+        it('should add an embedded ToC element if there is an `<h1>` heading', () => {
+          doPrepareTitleAndToc(DOC_WITH_H1);
+          const tocEl = getTocEl()!;
 
-        expect(tocEl).toBeTruthy();
-        expect(tocEl.classList.contains('embedded')).toBe(true);
-      });
+          expect(tocEl).toBeTruthy();
+          expect(tocEl.classList.contains('embedded')).toBe(true);
+        });
 
-      it('should not add a ToC element if there is a `.no-toc` `<h1>` heading', () => {
-        doPrepareTitleAndToc(DOC_WITH_NO_TOC_H1);
-        expect(getTocEl()).toBeFalsy();
+        it('should not add a second ToC element if there a hard coded one in place', () => {
+          doPrepareTitleAndToc(DOC_WITH_EMBEDDED_TOC);
+          expect(targetEl.querySelectorAll('aio-toc').length).toEqual(1);
+        });
       });
 
-      it('should not add a ToC element if there is no `<h1>` heading', () => {
-        doPrepareTitleAndToc(DOC_WITHOUT_H1);
-        expect(getTocEl()).toBeFalsy();
 
-        doPrepareTitleAndToc(EMPTY_DOC);
-        expect(getTocEl()).toBeFalsy();
+      describe('not needed', () => {
+        it('should not add a ToC element if there is a `.no-toc` `<h1>` heading', () => {
+          doPrepareTitleAndToc(DOC_WITH_NO_TOC_H1);
+          expect(getTocEl()).toBeFalsy();
+        });
+
+        it('should not add a ToC element if there is no `<h1>` heading', () => {
+          doPrepareTitleAndToc(DOC_WITHOUT_H1);
+          expect(getTocEl()).toBeFalsy();
+
+          doPrepareTitleAndToc(EMPTY_DOC);
+          expect(getTocEl()).toBeFalsy();
+        });
+
+        it('should remove ToC a hard coded one', () => {
+          doPrepareTitleAndToc(DOC_WITH_EMBEDDED_TOC_WITHOUT_H1);
+          expect(getTocEl()).toBeFalsy();
+
+          doPrepareTitleAndToc(DOC_WITH_EMBEDDED_TOC_WITH_NO_TOC_H1);
+          expect(getTocEl()).toBeFalsy();
+        });
       });
 
+
       it('should generate ToC entries if there is an `<h1>` heading', () => {
         doAddTitleAndToc(DOC_WITH_H1, 'foo');
 

aio/src/app/layout/doc-viewer/doc-viewer.component.ts

@@ -112,10 +112,15 @@ export class DocViewerComponent implements DoCheck, OnDestroy {
    */
   protected prepareTitleAndToc(targetElem: HTMLElement, docId: string): () => void {
     const titleEl = targetElem.querySelector('h1');
-    const hasToc = !!titleEl && !/no-?toc/i.test(titleEl.className);
+    const needsToc = !!titleEl && !/no-?toc/i.test(titleEl.className);
+    const embeddedToc = targetElem.querySelector('aio-toc.embedded');
 
-    if (hasToc) {
+    if (needsToc && !embeddedToc) {
+      // Add an embedded ToC if it's needed and there isn't one in the content already.
       titleEl!.insertAdjacentHTML('afterend', '<aio-toc class="embedded"></aio-toc>');
+    } else if (!needsToc && embeddedToc) {
+      // Remove the embedded Toc if it's there and not needed.
+      embeddedToc.remove();
     }
 
     return () => {
@@ -127,7 +132,7 @@ export class DocViewerComponent implements DoCheck, OnDestroy {
       if (titleEl) {
         title = (typeof titleEl.innerText === 'string') ? titleEl.innerText : titleEl.textContent;
 
-        if (hasToc) {
+        if (needsToc) {
           this.tocService.genToc(targetElem, docId);
         }
       }

aio/src/styles/2-modules/_api-pages.scss

@@ -10,6 +10,16 @@
   }
 }
 
+.api-header {
+  display: flex;
+  align-items: center;
+
+  @media screen and (max-width: 600px) {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+}
+
 .api-body {
 
   .class-overview {

aio/src/styles/2-modules/_heading-anchors.scss

@@ -3,7 +3,7 @@
 
     .header-link {
       color: $mediumgray;
-      margin-left: 8px;
+      margin: 0 4px;
       text-decoration: none;
       user-select: none;
       visibility: hidden;

aio/src/styles/2-modules/_label.scss

@@ -38,6 +38,14 @@ label.raised, .api-header label {
 
 .api-header label {
 
+    // The API badges should be a little smaller
+    padding: 2px 10px;
+    font-size: 12px;
+
+    @media screen and (max-width: 600px) {
+        margin: 4px 0;
+    }
+
     &.api-status-label {
         background-color: $mediumgray;
     }

aio/src/styles/2-modules/_toc.scss

@@ -8,10 +8,16 @@
   overflow-x: hidden;
 }
 
-aio-toc {
-  &.embedded {
-    @media (min-width: 801px) {
-      display: none;
+aio-toc.embedded {
+  @media (min-width: 801px) {
+    display: none;
+  }
+
+  .toc-inner {
+    padding: 12px 0 0 0;
+
+    .toc-heading {
+      margin: 0 0 8px;
     }
   }
 }

aio/tools/transforms/templates/api/base.template.html

@@ -20,13 +20,13 @@
     {% for crumb in doc.breadCrumbs %}{% if not loop.last %} {$ slash() $} {% if crumb.path %}<a href="{$ crumb.path $}">{$ crumb.text $}</a>{% else %}{$ crumb.text $}{% endif %}{% endif %}{% endfor %}
   </div>
   <header class="api-header">
+    <h1>{$ doc.name $}</h1>
+    <label class="api-type-label {$ doc.docType $}">{$ doc.docType $}</label>
     {% if doc.deprecated !== undefined %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
     {% if doc.experimental !== undefined %}<label class="api-status-label experimental">experimental</label>{% endif %}
     {% if doc.stable !== undefined %}<label class="api-status-label stable">stable</label>{% endif %}
-    <label class="api-type-label {$ doc.docType $}">{$ doc.docType $}</label>
-    <h1>{$ doc.name $}</h1>
-    <span class="version">{$ version $}</span>
   </header>
+  <aio-toc class="embedded"></aio-toc>
 
   <div class="api-body">
     {% block body %}{% endblock %}