docs: add markdown docs for NavMenu components (#256)

* docs: make adjacent code samples appear closer to each other * docs: add markdown documentation for navigation components * chore: update changelog * docs: show JSX language name on code snippets
influxdata · Aug 30, 2019 · 32affd5 · 32affd5
1 parent 546d52b
commit 32affd5
Show file tree

Hide file tree

Showing 7 changed files with 317 additions and 122 deletions.
diff --git a/.storybook/Story.scss b/.storybook/Story.scss
@@ -460,6 +460,32 @@ body.sb-show-main {
       background-color: transparent;
     }
   }
+
+  pre + pre {
+    margin-top: -1em;
+  }
+
+  pre.language-tsx {
+    position: relative;
+
+    &:after {
+      content: 'JSX';
+      display: inline-block;
+      position: absolute;
+      top: 0;
+      right: 0;
+      color: $g8-storm;
+      font-size: 11px;
+      height: 18px;
+      line-height: 18px;
+      padding: 0 6px;
+      white-space: nowrap;
+      font-weight: 600;
+      text-shadow: none;
+      background-color: $g0-obsidian;
+      border-bottom-left-radius: 6px;
+    }
+  }
 }
 
 .storybook-readme-story div.markdown-body table {

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ### 0.0.28 (Unreleased)
 
+- [#256](https://github.com/influxdata/clockface/pull/256): Add markdown documentation for `NavMenu` component family
 - [#252](https://github.com/influxdata/clockface/pull/252): Add new colors and gradients from InfluxData Brand guidelines
 - [#251](https://github.com/influxdata/clockface/pull/251): Introduce `Wand`, `WrenchNav`, and `DisksNav` icons to icon font
 

diff --git a/src/Components/NavMenu/NavMenu.md b/src/Components/NavMenu/NavMenu.md
@@ -0,0 +1,36 @@
+# NavMenu
+
+This is primary navigation component for Clockface applications. It is intentionally minimalistic to maximize screen space for application features. On small screens it moves to the top.
+
+### Usage
+```tsx
+import {NavMenu} from '@influxdata/clockface'
+```
+```tsx
+<NavMenu>
+  <NavMenu.Item>
+    <NavMenu.SubItem />
+  </NavMenu.Item>
+  <NavMenu.Item />
+</NavMenu>
+```
+
+### As Part of an Application Layout
+
+We recommend using `NavMenu` in combination with `AppWrapper` and `Page` to have all the basics for an application:
+```tsx
+<AppWrapper>
+  <NavMenu />
+  <Page />
+</AppWrapper>
+```
+
+### Example
+<!-- STORY -->
+
+
+<!-- STORY HIDE START -->
+
+<!-- STORY HIDE END -->
+
+<!-- PROPS -->
diff --git a/src/Components/NavMenu/NavMenu.stories.tsx b/src/Components/NavMenu/NavMenu.stories.tsx
@@ -1,5 +1,6 @@
 // Libraries
 import * as React from 'react'
+import marked from 'marked'
 
 // Storybook
 import {storiesOf} from '@storybook/react'
@@ -14,6 +15,11 @@ import {Icon} from '../../Components/Icon/Icon'
 // Types
 import {IconFont} from '../../Types'
 
+// Notes
+import NavMenuReadme from './NavMenu.md'
+import NavMenuItemReadme from './NavMenuItem.md'
+import NavMenuSubItemReadme from './NavMenuSubItem.md'
+
 const navMenuStories = storiesOf('Components|Navigation/NavMenu', module)
   .addDecorator(withKnobs)
   .addDecorator(jsxDecorator)
@@ -24,138 +30,176 @@ enum NavItems {
   Third = 'Third',
 }
 
-navMenuStories.add('NavMenu', () => (
-  <NavMenu hide={boolean('hide', false)}>
-    <NavMenu.Item
-      titleLink={className => (
-        <a className={className} href="#">
-          {text('1 - title', 'First Item')}
-        </a>
-      )}
-      iconLink={className => (
-        <a className={className} href="#">
-          <Icon
-            glyph={IconFont[select('1 - icon', mapEnumKeys(IconFont), 'Disks')]}
+navMenuStories.add(
+  'NavMenu',
+  () => (
+    <div className="story--example">
+      <NavMenu hide={boolean('hide', false)}>
+        <NavMenu.Item
+          titleLink={className => (
+            <a className={className} href="#">
+              {text('1 - title', 'First Item')}
+            </a>
+          )}
+          iconLink={className => (
+            <a className={className} href="#">
+              <Icon
+                glyph={
+                  IconFont[select('1 - icon', mapEnumKeys(IconFont), 'Disks')]
+                }
+              />
+            </a>
+          )}
+          active={
+            NavItems[radios<NavItems>('active item', mapEnumKeys(NavItems))] ==
+            NavItems.First
+          }
+        />
+        <NavMenu.Item
+          titleLink={className => (
+            <a className={className} href="#">
+              {text('2 - title', 'Second Item')}
+            </a>
+          )}
+          iconLink={className => (
+            <a className={className} href="#">
+              <Icon
+                glyph={
+                  IconFont[select('2 - icon', mapEnumKeys(IconFont), 'Zap')]
+                }
+              />
+            </a>
+          )}
+          active={
+            NavItems[radios<NavItems>('active item', mapEnumKeys(NavItems))] ==
+            NavItems.Second
+          }
+        >
+          <NavMenu.SubItem
+            titleLink={className => (
+              <a className={className} href="#">
+                First Sub-Item
+              </a>
+            )}
+            active={false}
           />
-        </a>
-      )}
-      active={
-        NavItems[radios<NavItems>('active item', mapEnumKeys(NavItems))] ==
-        NavItems.First
-      }
-    />
-    <NavMenu.Item
-      titleLink={className => (
-        <a className={className} href="#">
-          {text('2 - title', 'Second Item')}
-        </a>
-      )}
-      iconLink={className => (
-        <a className={className} href="#">
-          <Icon
-            glyph={IconFont[select('2 - icon', mapEnumKeys(IconFont), 'Zap')]}
+          <NavMenu.SubItem
+            titleLink={className => (
+              <a className={className} href="#">
+                Second Sub-Item
+              </a>
+            )}
+            active={false}
           />
-        </a>
-      )}
-      active={
-        NavItems[radios<NavItems>('active item', mapEnumKeys(NavItems))] ==
-        NavItems.Second
-      }
-    >
-      <NavMenu.SubItem
+          <NavMenu.SubItem
+            titleLink={className => (
+              <a className={className} href="#">
+                Third Sub-Item
+              </a>
+            )}
+            active={false}
+          />
+        </NavMenu.Item>
+        <NavMenu.Item
+          titleLink={className => (
+            <a className={className} href="#">
+              {text('3 - title', 'Third Item')}
+            </a>
+          )}
+          iconLink={className => (
+            <a className={className} href="#">
+              <Icon
+                glyph={
+                  IconFont[select('3 - icon', mapEnumKeys(IconFont), 'Group')]
+                }
+              />
+            </a>
+          )}
+          active={
+            NavItems[radios<NavItems>('active item', mapEnumKeys(NavItems))] ==
+            NavItems.Third
+          }
+        />
+      </NavMenu>
+    </div>
+  ),
+  {
+    readme: {
+      content: marked(NavMenuReadme),
+    },
+  }
+)
+
+navMenuStories.add(
+  'NavMenuItem',
+  () => (
+    <div className="story--example">
+      <NavMenu.Item
         titleLink={className => (
           <a className={className} href="#">
-            First Sub-Item
+            {text('title', 'Item Title')}
           </a>
         )}
-        active={false}
-      />
-      <NavMenu.SubItem
-        titleLink={className => (
+        iconLink={className => (
           <a className={className} href="#">
-            Second Sub-Item
+            <Icon
+              glyph={IconFont[select('icon', mapEnumKeys(IconFont), 'Star')]}
+            />
           </a>
         )}
-        active={false}
-      />
+        active={boolean('active', false)}
+      >
+        <NavMenu.SubItem
+          titleLink={className => (
+            <a className={className} href="#">
+              First Sub-Item
+            </a>
+          )}
+          active={false}
+        />
+        <NavMenu.SubItem
+          titleLink={className => (
+            <a className={className} href="#">
+              Second Sub-Item
+            </a>
+          )}
+          active={false}
+        />
+        <NavMenu.SubItem
+          titleLink={className => (
+            <a className={className} href="#">
+              Third Sub-Item
+            </a>
+          )}
+          active={false}
+        />
+      </NavMenu.Item>
+    </div>
+  ),
+  {
+    readme: {
+      content: marked(NavMenuItemReadme),
+    },
+  }
+)
+
+navMenuStories.add(
+  'NavMenuSubItem',
+  () => (
+    <div className="story--example">
       <NavMenu.SubItem
         titleLink={className => (
           <a className={className} href="#">
-            Third Sub-Item
+            {text('title', 'Sub Item Title')}
           </a>
         )}
-        active={false}
+        active={boolean('active', false)}
       />
-    </NavMenu.Item>
-    <NavMenu.Item
-      titleLink={className => (
-        <a className={className} href="#">
-          {text('3 - title', 'Third Item')}
-        </a>
-      )}
-      iconLink={className => (
-        <a className={className} href="#">
-          <Icon
-            glyph={IconFont[select('3 - icon', mapEnumKeys(IconFont), 'Group')]}
-          />
-        </a>
-      )}
-      active={
-        NavItems[radios<NavItems>('active item', mapEnumKeys(NavItems))] ==
-        NavItems.Third
-      }
-    />
-  </NavMenu>
-))
-
-navMenuStories.add('NavMenuItem', () => (
-  <NavMenu.Item
-    titleLink={className => (
-      <a className={className} href="#">
-        {text('title', 'Item Title')}
-      </a>
-    )}
-    iconLink={className => (
-      <a className={className} href="#">
-        <Icon glyph={IconFont[select('icon', mapEnumKeys(IconFont), 'Star')]} />
-      </a>
-    )}
-    active={boolean('active', false)}
-  >
-    <NavMenu.SubItem
-      titleLink={className => (
-        <a className={className} href="#">
-          First Sub-Item
-        </a>
-      )}
-      active={false}
-    />
-    <NavMenu.SubItem
-      titleLink={className => (
-        <a className={className} href="#">
-          Second Sub-Item
-        </a>
-      )}
-      active={false}
-    />
-    <NavMenu.SubItem
-      titleLink={className => (
-        <a className={className} href="#">
-          Third Sub-Item
-        </a>
-      )}
-      active={false}
-    />
-  </NavMenu.Item>
-))
-
-navMenuStories.add('NavMenuSubItem', () => (
-  <NavMenu.SubItem
-    titleLink={className => (
-      <a className={className} href="#">
-        {text('title', 'Sub Item Title')}
-      </a>
-    )}
-    active={boolean('active', false)}
-  />
-))
+    </div>
+  ),
+  {
+    readme: {
+      content: marked(NavMenuSubItemReadme),
+    },
+  }
+)