From 0d48efb57b89785239a1ccb733662b9fd9b49724 Mon Sep 17 00:00:00 2001
From: Christopher Garrett <opensource@pzuraq.com>
Date: Fri, 4 May 2018 18:33:24 -0700
Subject: [PATCH] [cleanup] Simplify the API doc navigation

* Simplifies the API doc navigation. It now only shows the modules
themselves, and none of their items (that is left to the API docs page).

* Brings back nested subnavigation menus

* Adds the `break-on` helper which allows us to specify when a string
should break by inserting zero-width spaces
---
 addon/components/docs-hero/template.hbs       | 30 +++++++-------
 .../docs-viewer/x-nav-item/component.js       |  4 +-
 .../docs-viewer/x-nav-list/component.js       | 13 ++++---
 .../docs-viewer/x-nav-list/template.hbs       |  5 ---
 .../components/docs-viewer/x-nav/template.hbs | 34 ++++------------
 .../docs-viewer/x-page-index/template.hbs     |  2 +-
 .../docs-viewer/x-section/component.js        | 16 +++++---
 .../docs-viewer/x-section/template.hbs        |  7 ----
 addon/helpers/break-on.js                     | 13 +++++++
 lib/broccoli/docs-compiler.js                 | 39 +++++++------------
 package.json                                  |  4 +-
 .../acceptance/sandbox/api/components-test.js | 12 +++---
 12 files changed, 77 insertions(+), 102 deletions(-)
 delete mode 100644 addon/components/docs-viewer/x-nav-list/template.hbs
 delete mode 100644 addon/components/docs-viewer/x-section/template.hbs
 create mode 100644 addon/helpers/break-on.js

diff --git a/addon/components/docs-hero/template.hbs b/addon/components/docs-hero/template.hbs
index 1c0a691c8..a5c804613 100644
--- a/addon/components/docs-hero/template.hbs
+++ b/addon/components/docs-hero/template.hbs
@@ -3,23 +3,21 @@
   {{if (eq style 'light') 'text-grey-darkest'}}
   {{if (eq style 'dark') 'bg-black text-white'}}
 ">
-  <div class='docs-container'>
-    <h1 class='text-5xl md:text-jumbo leading-none'>
-      {{#if logo}}
-        <div class='md:-mb-1 -mt-4 md:-mt-8'>
-          <span class='inline-block h-6 opacity-50'>
-            {{docs-logo logo=logo}}
-          </span>
-        </div>
-      {{/if}}
+  <h1 class='text-5xl md:text-jumbo leading-none'>
+    {{#if logo}}
+      <div class='md:-mb-1 -mt-4 md:-mt-8'>
+        <span class='inline-block h-6 opacity-50'>
+          {{docs-logo logo=logo}}
+        </span>
+      </div>
+    {{/if}}
 
-      <span class='font-thin'>{{slimHeading}}</span>{{strongHeading}}
-    </h1>
+    <span class='font-thin'>{{slimHeading}}</span>{{strongHeading}}
+  </h1>
 
-    <p class='opacity-75 text-xl mt-4 w-3/4 mx-auto leading-tight'>
-      {{byline}}
-    </p>
+  <p class='opacity-75 text-xl mt-4 w-3/4 mx-auto leading-tight'>
+    {{byline}}
+  </p>
 
-    {{yield}}
-  </div>
+  {{yield}}
 </div>
diff --git a/addon/components/docs-viewer/x-nav-item/component.js b/addon/components/docs-viewer/x-nav-item/component.js
index 65d928b55..10427a7b3 100644
--- a/addon/components/docs-viewer/x-nav-item/component.js
+++ b/addon/components/docs-viewer/x-nav-item/component.js
@@ -1,8 +1,9 @@
 import { inject as service } from '@ember/service';
 import Component from '@ember/component';
-import layout from './template';
 import { next } from '@ember/runloop';
 
+import layout from './template';
+
 export default Component.extend({
   layout,
   tagName: '',
@@ -21,7 +22,6 @@ export default Component.extend({
       this.get('docsRoutes.items').addObject(this);
     });
   }
-
 }).reopenClass({
 
   positionalParams: ['label', 'route', 'model']
diff --git a/addon/components/docs-viewer/x-nav-list/component.js b/addon/components/docs-viewer/x-nav-list/component.js
index bd0276f96..f453371a0 100644
--- a/addon/components/docs-viewer/x-nav-list/component.js
+++ b/addon/components/docs-viewer/x-nav-list/component.js
@@ -1,11 +1,14 @@
 import Component from '@ember/component';
-import layout from './template';
+import hbs from 'htmlbars-inline-precompile'
 
 export default Component.extend({
-  layout,
+  tagName: 'ul',
 
-  tagName: ''
-
-  // classNames: 'docs-viewer__nav-list'
+  classNames: ['list-reset'],
 
+  layout: hbs`
+    {{yield (hash
+      item=(component 'docs-viewer/x-nav-item')
+    )}}
+  `
 });
diff --git a/addon/components/docs-viewer/x-nav-list/template.hbs b/addon/components/docs-viewer/x-nav-list/template.hbs
deleted file mode 100644
index 7da86ea18..000000000
--- a/addon/components/docs-viewer/x-nav-list/template.hbs
+++ /dev/null
@@ -1,5 +0,0 @@
-<ul class='list-reset'>
-  {{yield (hash
-    item=(component 'docs-viewer/x-nav-item')
-  )}}
-</ul>
diff --git a/addon/components/docs-viewer/x-nav/template.hbs b/addon/components/docs-viewer/x-nav/template.hbs
index 81c8d46f9..f56457b3d 100644
--- a/addon/components/docs-viewer/x-nav/template.hbs
+++ b/addon/components/docs-viewer/x-nav/template.hbs
@@ -31,40 +31,20 @@
       {{yield (hash
         section=(component 'docs-viewer/x-section')
         item=(component 'docs-viewer/x-nav-item')
-        subnav=(component 'docs-viewer/x-nav-list')
+        subnav=(component 'docs-viewer/x-nav-list' class='ml-4')
       )}}
 
       {{!-- Autogenerated API docs --}}
       {{#if (gt project.modules.length 0)}}
         {{docs-viewer/x-section 'API Reference' style='large'}}
 
-        {{#docs-viewer/x-nav-list as |subnav|}}
-          {{#each-in project.navigationIndex as |type items|}}
-            {{docs-viewer/x-section type}}
+        {{#each-in project.navigationIndex as |type items|}}
+          {{docs-viewer/x-section type}}
 
-            {{#docs-viewer/x-nav-list as |subnav|}}
-              {{#if (is-array items)}}
-                {{#each items as |item|}}
-                  {{subnav.item item.name (concat root '.api.item') item.path}}
-                {{/each}}
-              {{else}}
-                {{#each-in items as |module items|}}
-                  {{subnav.item module
-                    (concat root '.api.item')
-                    (concat 'modules/' module)
-                    class="docs-viewer__module-heading"
-                  }}
-
-                  {{#docs-viewer/x-nav-list as |subnav|}}
-                    {{#each items as |item|}}
-                      {{subnav.item item.name (concat root '.api.item') item.path}}
-                    {{/each}}
-                  {{/docs-viewer/x-nav-list}}
-                {{/each-in}}
-              {{/if}}
-            {{/docs-viewer/x-nav-list}}
-          {{/each-in}}
-        {{/docs-viewer/x-nav-list}}
+          {{#each items as |item|}}
+            {{docs-viewer/x-nav-item (break-on item.name '/') (concat root '.api.item') item.path}}
+          {{/each}}
+        {{/each-in}}
       {{/if}}
     {{/docs-viewer/x-nav-list}}
 
diff --git a/addon/components/docs-viewer/x-page-index/template.hbs b/addon/components/docs-viewer/x-page-index/template.hbs
index 469f4e672..bafa24c1a 100644
--- a/addon/components/docs-viewer/x-page-index/template.hbs
+++ b/addon/components/docs-viewer/x-page-index/template.hbs
@@ -1,5 +1,5 @@
 <nav class="hidden lg:block lg:w-1/5 pl-4" data-test-page-index>
-  <div class="sticky pin-t pt-4 -mt-4 max-h-screen overflow-y-scroll">
+  <div class="sticky pin-t pt-4 pb-8 -mt-4 max-h-screen overflow-y-scroll">
     <ul class="list-reset border-l border-grey-lighter pl-6 leading-normal">
       {{#if pageIndex.length}}
         <li class="mt-20 text-grey font-bold tracking-wide uppercase text-xs">
diff --git a/addon/components/docs-viewer/x-section/component.js b/addon/components/docs-viewer/x-section/component.js
index 4780297de..0b3f60324 100644
--- a/addon/components/docs-viewer/x-section/component.js
+++ b/addon/components/docs-viewer/x-section/component.js
@@ -1,12 +1,18 @@
 import Component from '@ember/component';
-import layout from './template';
+import hbs from 'htmlbars-inline-precompile';
 
 export default Component.extend({
+  tagName: '',
 
-  layout,
-
-  tagName: ''
-
+  layout: hbs`
+    <li class='
+      mt-8 text-grey font-bold
+      tracking-wide uppercase
+      {{if (eq style 'large') '-mb-4 text-sm' 'text-xs'}}
+    '>
+      {{label}}
+    </li>
+  `
 }).reopenClass({
 
   positionalParams: [ 'label' ]
diff --git a/addon/components/docs-viewer/x-section/template.hbs b/addon/components/docs-viewer/x-section/template.hbs
deleted file mode 100644
index 1a8c12280..000000000
--- a/addon/components/docs-viewer/x-section/template.hbs
+++ /dev/null
@@ -1,7 +0,0 @@
-<li class='
-  mt-8 text-grey font-bold
-  tracking-wide uppercase
-  {{if (eq style 'large') '-mb-4 text-sm' 'text-xs'}}
-'>
-  {{label}}
-</li>
diff --git a/addon/helpers/break-on.js b/addon/helpers/break-on.js
new file mode 100644
index 000000000..795d7f86d
--- /dev/null
+++ b/addon/helpers/break-on.js
@@ -0,0 +1,13 @@
+import { helper } from '@ember/component/helper';
+
+/**
+  Helper function that inserts zero-width spaces after the break character, so
+  that the string will break when wrapping only after that character.
+
+  @hide
+*/
+export function breakOn([string, breakChar]) {
+  return string.replace(new RegExp(breakChar, 'g'), `${breakChar}\u200B`)
+}
+
+export default helper(breakOn);
diff --git a/lib/broccoli/docs-compiler.js b/lib/broccoli/docs-compiler.js
index 52ce54781..7c2586a70 100644
--- a/lib/broccoli/docs-compiler.js
+++ b/lib/broccoli/docs-compiler.js
@@ -109,26 +109,6 @@ function generateResolvedTypeNavigationItems(modules, type) {
   return _.sortBy(items, ['path']);
 }
 
-function generateModuleNavigationItems(modules, type) {
-  return modules.reduce((navItems, m) => {
-    let items = m[type].map((item) => {
-      let path = item.id ? item.id : `${m.id}#${item.name}`;
-
-      return {
-        path: `modules/${path}`,
-        name: item.name,
-        isDefault: item.exportType === 'default'
-      };
-    });
-
-    if (items.length > 0) {
-      navItems[m.file] = _.sortBy(items, ['name']);
-    }
-
-    return navItems;
-  }, {});
-}
-
 function generateNavigationIndex(modules, klasses) {
   let navigationIndex = {};
 
@@ -138,13 +118,20 @@ function generateNavigationIndex(modules, klasses) {
     navigationIndex[type] = generateResolvedTypeNavigationItems(resolvedModules, type);
   }
 
-  let nonResolvedModules = modules.filter(m => {
-    return !m.file.match(new RegExp(`(${RESOLVED_TYPES.join('|')})/`)) || m.file.match('utils/');
-  })
+  navigationIndex.modules = modules
+    .filter(m => {
+      return (
+        !m.file.match(new RegExp(`(${RESOLVED_TYPES.join('|')})/`)) ||
+        m.file.match('utils/')
+      );
+    })
+    .map(m => {
+      return {
+        path: `modules/${m.id}`,
+        name: m.id
+      };
+    });
 
-  navigationIndex.classes = generateModuleNavigationItems(nonResolvedModules, 'classes');
-  navigationIndex.functions = generateModuleNavigationItems(nonResolvedModules, 'functions');
-  navigationIndex.variables = generateModuleNavigationItems(nonResolvedModules, 'variables');
 
   for (let type in navigationIndex) {
     let items = navigationIndex[type];
diff --git a/package.json b/package.json
index 6863e9081..01c520aca 100644
--- a/package.json
+++ b/package.json
@@ -36,9 +36,10 @@
     "ember-cli-babel": "^6.11.0",
     "ember-cli-clipboard": "^0.8.1",
     "ember-cli-htmlbars": "^2.0.3",
+    "ember-cli-htmlbars-inline-precompile": "^1.0.2",
     "ember-cli-sass": "7.1.3",
     "ember-cli-string-helpers": "^1.7.0",
-    "ember-cli-tailwind": "0.4.0",
+    "ember-cli-tailwind": "^0.4.1",
     "ember-code-snippet": "^2.1.0",
     "ember-component-css": "^0.3.5",
     "ember-concurrency": "^0.8.16",
@@ -87,7 +88,6 @@
     "ember-cli-deploy-git": "^1.3.2",
     "ember-cli-deploy-git-ci": "^1.0.1",
     "ember-cli-eslint": "^4.2.3",
-    "ember-cli-htmlbars-inline-precompile": "^1.0.2",
     "ember-cli-inject-live-reload": "^1.7.0",
     "ember-cli-mirage": "^0.4.5",
     "ember-cli-qunit": "^4.3.0",
diff --git a/tests/acceptance/sandbox/api/components-test.js b/tests/acceptance/sandbox/api/components-test.js
index a765e2654..49078ae89 100644
--- a/tests/acceptance/sandbox/api/components-test.js
+++ b/tests/acceptance/sandbox/api/components-test.js
@@ -11,20 +11,20 @@ module('Acceptance | API | components', function(hooks) {
 
   test('nested components work', async function(assert) {
     await visit('/sandbox');
-    await modulePage.navItems.findOne({ text: `{{simple-list}}` }).click();
+    await modulePage.navItems.findOne({ text: '{{simple-list}}' }).click();
 
-    assert.equal(currentURL(), `/sandbox/api/components/simple-list`, 'correct url');
+    assert.equal(currentURL(), '/sandbox/api/components/simple-list', 'correct url');
 
-    await modulePage.navItems.findOne({ text: `{{simple-list/item}}` }).click();
+    await modulePage.navItems.findOne({ text: '{{simple-list/\u200Bitem}}' }).click();
 
-    assert.equal(currentURL(), `/sandbox/api/components/simple-list/item`, 'correct url');
+    assert.equal(currentURL(), '/sandbox/api/components/simple-list/item', 'correct url');
   });
 
   test('component page index works', async function(assert) {
     await visit('/sandbox');
-    await modulePage.navItems.findOne({ text: `{{esdoc-component}}` }).click();
+    await modulePage.navItems.findOne({ text: '{{esdoc-component}}' }).click();
 
-    assert.equal(currentURL(), `/sandbox/api/components/esdoc-component`, 'correct url');
+    assert.equal(currentURL(), '/sandbox/api/components/esdoc-component', 'correct url');
 
     let indexItems = modulePage.index.items.map(i => i.text);