feat(nav): Enable override of nav item list via shadowing (#560)

* feat(nav): refactor nav item list to enable shadowing
Refactor building of the nav item list to standalone file for override
Enables alternate mechanisms for building the nav item list

* reorder import line for cleaner diff from upstream

* reorder file for cleaner diff with upstream

* docs: add documentation to accompany PR #560
shows how to customize the left nav via Gatsby shadowing

packages/example/src/pages/guides/navigation/sidebar.mdx

@@ -33,3 +33,25 @@ Some important things to note here:
 - The `path` refer to the relative path to the mdx file in your pages
 - You can make a `Page/index.mdx` file if you'd prefer to have assets in a folder.
   The path would still just look like `/Page`
+
+## Customizing
+
+The nav item list can be customized using Gatsby theme [shadowing](../shadowing).
+Simply provide your own implementation of `src/components/LeftNav/LeftNavItemProvider.js` which can augment or replace the nav items read from `src/data/nav-items.yaml`.
+
+```javascript
+// src/gatsby-theme-carbon/components/LeftNav/LeftNavItemProvider.js
+import { useNavItems as themeUseNavItems } from 'gatsby-theme-carbon/src/components/LeftNav/LeftNavItemProvider';
+
+// add nav items
+export function useNavItems() {
+  const navItems = themeUseNavItems();
+  return navItems.concat({
+    title: 'Additional Nav Item',
+    pages: [
+      { path: '/page1', title: 'New Page 1' },
+      { path: '/page2', title: 'New Page 2' },
+    ],
+  });
+}
+```

packages/gatsby-theme-carbon/src/components/LeftNav/LeftNav.js

@@ -1,6 +1,6 @@
 import React, { useContext } from 'react';
 import classnames from 'classnames';
-import { useStaticQuery, graphql } from 'gatsby';
+import { useNavItems } from './LeftNavItemProvider';
 
 import {
   SideNav,
@@ -23,25 +23,7 @@ const LeftNav = props => {
     toggleNavState('leftNavIsOpen', 'open');
   }
 
-  const {
-    allNavItemsYaml: { edges },
-  } = useStaticQuery(graphql`
-    query LEFT_NAV_QUERY {
-      allNavItemsYaml {
-        edges {
-          node {
-            title
-            pages {
-              title
-              path
-            }
-          }
-        }
-      }
-    }
-  `);
-
-  const navItems = edges.map(({ node }) => node);
+  const navItems = useNavItems();
 
   const renderNavItems = () =>
     navItems.map((item, i) => (

packages/gatsby-theme-carbon/src/components/LeftNav/LeftNavItemProvider.js

@@ -0,0 +1,24 @@
+import { useStaticQuery, graphql } from 'gatsby';
+
+export function useNavItems() {
+  const {
+    allNavItemsYaml: { edges },
+  } = useStaticQuery(graphql`
+    query LEFT_NAV_QUERY {
+      allNavItemsYaml {
+        edges {
+          node {
+            title
+            pages {
+              title
+              path
+            }
+          }
+        }
+      }
+    }
+  `);
+
+  const navItems = edges.map(({ node }) => node);
+  return navItems;
+}