feat: 791-header-shell-links-removing-left-nav

packages/example/gatsby-config.js

@@ -20,7 +20,6 @@ module.exports = {
     {
       resolve: 'gatsby-theme-carbon',
       options: {
-        isSearchEnabled: true,
         mediumAccount: 'carbondesign',
         repository: {
           baseUrl:

packages/example/src/pages/guides/configuration.mdx

@@ -16,6 +16,7 @@ Gatsby themes allow you to override configuration from the theme by defining the
   <AnchorLink>Additional font weights</AnchorLink>
   <AnchorLink>Image compression</AnchorLink>
   <AnchorLink>Global search</AnchorLink>
+  <AnchorLink>Navigation style</AnchorLink>
   <AnchorLink>Edit on Github link</AnchorLink>
   <AnchorLink>Medium</AnchorLink>
   <AnchorLink>Other options</AnchorLink>
@@ -139,6 +140,38 @@ Global search is enabled by default. To disable it, set the `isSearchEnabled` op
 Under the hood, we use [Lunr](https://lunrjs.com/) to create our search index. If necessary, you tweak the search scoring algorithm and source nodes.
 To do so, provide your own [resolvers object](https://www.gatsbyjs.org/packages/gatsby-plugin-lunr/#getting-started) to the `lunrOptions` theme option.
 
+## Navigation style
+
+By default, the navigation style used by the theme is a sidebar that sits on the left-hand side of the screen. You can see it right now as you read this documentation. This style works great for websites with a lot of content, like documentation sites. 
+
+However, if your site is more editorial in nature, and has less pages of content, you may want to use the `header` navigation. This will remove the sidebar on the left-hand side of the page and replace it with a navigation menu that sits in the header. If in the future, the content on your site evolves and you feel the left nav is better suited, you can always change it back.
+
+To enable the header nav, provide `header` as a string to the `navigationStyle` option. To switch back to the default left nav provide an empty string `''` to the `navigationStyle` option. Note: By using the `header` navigation style, you will lose the ResourceLinks that sit directly below the left nav.
+
+```js
+  plugins: [
+    {
+      resolve: 'gatsby-theme-carbon',
+      options: {
+        navigationStyle: 'header',
+      },
+    },
+  ],
+```
+When enabled, your header navigation will look like the image below: 
+
+<Row>
+<Column colMd={8} colLg={8}>
+
+![Header navigation style](header-nav-config.png)
+
+</Column>
+</Row>
+
+With the header navigation style enabled, the content on your page will be further left-aligned to allow for more content space.
+
+**Just a note:** In mobile-view, when the header navigation is enabled, the sidebar will persist.
+
 ## Edit on GitHub link
 
 To add a link to the bottom of each page that points to the current page source in GitHub, provide a `repository` object to `siteMetadata` in your `gatsby-config.js` file. You can provide a `baseUrl`, and if needed, the `subDirectory` and `branch` where your site source lives.
@@ -287,4 +320,4 @@ After installing the `remark-grid-tables` plugin, add it to the `remarkPlugins`
       },
     },
   ],
-```
+```

packages/gatsby-theme-carbon/gatsby-config.js

@@ -10,7 +10,8 @@ module.exports = (themeOptions) => {
   };
 
   const {
-    isSearchEnabled = true,
+    isSearchEnabled = true,	
+    navigationStyle = '',
     withWebp = false,
     iconPath,
     mdxExtensions = ['.mdx', '.md'],
@@ -57,6 +58,7 @@ module.exports = (themeOptions) => {
   return {
     siteMetadata: {
       isSearchEnabled,
+      navigationStyle,
       title: 'Gatsby Theme Carbon',
       description:
         'Add a description by supplying it to siteMetadata in your gatsby-config.js file.',

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

@@ -4,6 +4,7 @@ import classnames from 'classnames';
 import cx from 'classnames';
 import NavContext from '../../util/context/NavContext';
 import useWindowSize from '../../util/hooks/useWindowSize';
+import useMetadata from '../../util/hooks/useMetadata';
 import { overlay, visible } from './Container.module.scss';
 
 const Container = ({ children, homepage, theme }) => {
@@ -12,6 +13,7 @@ const Container = ({ children, homepage, theme }) => {
   );
   const windowSize = useWindowSize();
   const lastWindowSize = useRef(windowSize);
+  const { navigationStyle } = useMetadata();
 
   const closeNavs = useCallback(() => {
     toggleNavState('leftNavIsOpen', 'close');
@@ -37,6 +39,7 @@ const Container = ({ children, homepage, theme }) => {
     container: true,
     'container--homepage': homepage,
     'container--dark': theme === 'dark',
+    'container--header--nav': navigationStyle,
   });
 
   return (

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

@@ -10,6 +10,7 @@ import {
 import { AppSwitcher20, Close20 } from '@carbon/icons-react';
 import cx from 'classnames';
 
+import HeaderNav from '../HeaderNav/HeaderNav';
 import GlobalSearch from '../GlobalSearch';
 import NavContext from '../../util/context/NavContext';
 import useMetadata from '../../util/hooks/useMetadata';
@@ -31,7 +32,7 @@ const Header = ({ children }) => {
     switcherIsOpen,
     searchIsOpen,
   } = useContext(NavContext);
-  const { isSearchEnabled } = useMetadata();
+  const { isSearchEnabled, navigationStyle } = useMetadata();
 
   return (
     <ShellHeader aria-label="Header" className={header}>
@@ -53,6 +54,7 @@ const Header = ({ children }) => {
       >
         {children}
       </Link>
+      {navigationStyle && <HeaderNav />}
       <HeaderGlobalBar>
         {isSearchEnabled && <GlobalSearch />}
         <HeaderGlobalAction

packages/gatsby-theme-carbon/src/components/Header/Header.module.scss

@@ -56,7 +56,6 @@ header.header {
   transition: opacity $duration--fast-02 $carbon--standard-easing;
   color: $inverse-01;
   text-decoration: none;
-  position: absolute;
   left: 3rem;
   white-space: nowrap;
   padding: 0 $spacing-05;

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

@@ -0,0 +1,20 @@
+import React from 'react';
+
+import { HeaderNavigation } from 'carbon-components-react/lib/components/UIShell';
+import HeaderNavItem from './HeaderNavItem';
+
+import { useNavItems } from '../../util/NavItems';
+
+const HeaderNav = () => {
+  const navItems = useNavItems();
+
+  return (
+    <HeaderNavigation aria-label="Carbon Design System">
+      {navItems.map(({pages, title}) => (
+        <HeaderNavItem items={pages} category={title} key={title} />
+      ))}
+    </HeaderNavigation>
+  );
+};
+
+export default HeaderNav;

packages/gatsby-theme-carbon/src/components/HeaderNav/HeaderNavItem.js

@@ -0,0 +1,95 @@
+import React, { useContext } from 'react';
+
+import { Link } from 'gatsby';
+import { Location } from '@reach/router';
+import cx from 'classnames';
+
+import {
+  HeaderMenu,
+  HeaderMenuItem,
+} from 'carbon-components-react/lib/components/UIShell';
+import styles from '../Header/Header.module.scss';
+
+import NavContext from '../../util/context/NavContext';
+import usePathprefix from '../../util/hooks/usePathprefix';
+
+const HeaderNavItem = (props) => {
+  const { items, category } = props;
+  const { toggleNavState } = useContext(NavContext);
+  const closeLeftNav = () => toggleNavState('leftNavIsOpen', 'close');
+  const pathPrefix = usePathprefix();
+
+  return (
+    <Location>
+      {({ location }) => {
+        const pathname = pathPrefix
+          ? location.pathname.replace(pathPrefix, '')
+          : location.pathname;
+
+        const isActive = items.some(
+          (item) => item.path.split('/')[1] === pathname.split('/')[1]
+        );
+
+        if (items.length === 1) {
+          return (
+            <HeaderMenuItem
+              onClick={closeLeftNav}
+              icon={<span>dummy icon</span>}
+              element={Link}
+              isActive={isActive}
+              to={`${items[0].path}`}
+            >
+              {category}
+            </HeaderMenuItem>
+          );
+        }
+        return (
+          <HeaderMenu
+            icon={<span>dummy icon</span>}
+            isActive={isActive} // TODO similar categories
+            defaultExpanded={isActive}
+            title={category}
+            menuLinkName={category}
+          >
+            <TabItems
+              onClick={closeLeftNav}
+              items={items}
+              pathname={pathname}
+            />
+          </HeaderMenu>
+        );
+      }}
+    </Location>
+  );
+};
+
+const TabItems = ({ items, pathname, onClick }) =>
+  items.map((item, i) => {
+    const hasActiveTab =
+      item.path.split('/') > 3
+        ? item.path.split('/')[3] === pathname.split('/')[3]
+        : item.path.split('/')[2] === pathname.split('/')[2];
+
+    return (
+      <HeaderMenuItem
+        to={`${item.path}`}
+        className={cx({
+          [styles.linkText__dark]: pathname === '/',
+        })}
+        onClick={onClick}
+        element={Link}
+        isActive={hasActiveTab}
+        key={i}
+      >
+        <span
+          className={cx(styles.linkText, {
+            [styles.linkText__active]: hasActiveTab,
+          })}
+        >
+          {item.title}
+        </span>
+      </HeaderMenuItem>
+    );
+  });
+
+export default HeaderNavItem;

packages/gatsby-theme-carbon/src/components/HeaderNav/index.js

@@ -0,0 +1,3 @@
+import HeaderNav from './HeaderNav';
+
+export default HeaderNav;

packages/gatsby-theme-carbon/src/components/Homepage/homepage.scss

@@ -73,6 +73,20 @@
   }
 }
 
+.container--header--nav .#{$prefix}--grid {
+  margin: 0;
+
+  @include carbon--breakpoint("lg") {
+    padding-left: calc(
+      2% + 2rem
+    ); //2rem to account for 2rem left padding default on grid
+  }
+
+  @include carbon--breakpoint("max") {
+    padding-left: 2%;
+  }
+}
+
 .container--homepage .#{$prefix}--col-no-gutter {
   padding: 0;
 }

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

@@ -1,8 +1,8 @@
 /* eslint-disable import/no-unresolved */
 import React, { useLayoutEffect } from 'react';
 
-import LeftNav from './LeftNav';
 import Meta from './Meta';
+import LeftNav from './LeftNav';
 import Header from './Header';
 import Switcher from './Switcher';
 import Footer from './Footer';

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

@@ -1,14 +1,15 @@
 import React, { useContext, useRef, useEffect } from 'react';
 import classnames from 'classnames';
 import { SideNav, SideNavItems } from 'carbon-components-react';
-import { useNavItems } from './LeftNavItemProvider';
+import { useNavItems } from '../../util/NavItems';
 
 import NavContext from '../../util/context/NavContext';
 import LeftNavItem from './LeftNavItem';
 import LeftNavResourceLinks from './ResourceLinks';
 
 import LeftNavWrapper from './LeftNavWrapper';
 import { sideNavDark } from './LeftNav.module.scss';
+import useMetadata from '../../util/hooks/useMetadata';
 
 const LeftNav = (props) => {
   const { leftNavIsOpen, leftNavScrollTop, setLeftNavScrollTop } = useContext(
@@ -35,15 +36,20 @@ const LeftNav = (props) => {
   }, [leftNavScrollTop]);
 
   const navItems = useNavItems();
+  const { navigationStyle } = useMetadata();
 
   // TODO: replace old addon website styles with sass modules, move to wrapper
   return (
-    <LeftNavWrapper expanded={leftNavIsOpen}>
+    <LeftNavWrapper
+      expanded={leftNavIsOpen}
+      useHeaderNavigation={navigationStyle}
+    >
       <SideNav
         ref={sideNavRef}
-        expanded
-        defaultExpanded
         aria-label="Side navigation"
+        expanded={navigationStyle ? leftNavIsOpen : true}
+        defaultExpanded={!navigationStyle}
+        isPersistent={!navigationStyle}
         className={classnames({
           [sideNavDark]: props.theme === 'dark' || props.homepage,
           'bx--side-nav--website': true,

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

@@ -3,11 +3,13 @@ import cx from 'classnames';
 
 import {
   leftNavWrapper,
+  useHeaderNavStyles,
   expanded as expandedStyles,
 } from './LeftNavWrapper.module.scss';
 
-const LeftNavWrapper = ({ expanded, ...rest }) => {
+const LeftNavWrapper = ({ useHeaderNavigation, expanded, ...rest }) => {
   const className = cx(leftNavWrapper, {
+    [useHeaderNavStyles]: useHeaderNavigation,
     [expandedStyles]: expanded,
   });
   return <div className={className} {...rest} />;

packages/gatsby-theme-carbon/src/components/LeftNav/LeftNavWrapper.module.scss

@@ -12,18 +12,35 @@
     box-shadow: none !important;
   }
 
+  // LeftNav default style in desktop view.
   @include carbon--breakpoint("lg") {
     transform: translateX(0px);
   }
 }
 
+// HeaderNavigation default style in desktop view (hide LeftNav).
+.useHeaderNavStyles.leftNavWrapper {
+  @include carbon--breakpoint("lg") {
+    transform: translateX(-256px);
+  }
+}
+
+// Transition expanded LeftNav in mobile back to HeaderNavigation in dektop view.
+.useHeaderNavStyles.expanded {
+  @include carbon--breakpoint("lg") {
+    transform: translateX(-256px);
+  }
+}
+
 .leftNavWrapper :global(.bx--side-nav__navigation) {
   padding-top: 0;
   padding-bottom: 48px;
 }
 
+// Expand LeftNav in mobile for both HeaderNavigation & LeftNav default templates.
 .expanded {
   transform: translateX(0px);
+
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
   @include carbon--breakpoint("lg") {
     box-shadow: none;

packages/gatsby-theme-carbon/src/templates/Default.js

@@ -39,6 +39,7 @@ const Default = ({ pageContext, children, location, Title }) => {
   };
 
   const currentTab = getCurrentTab();
+
   return (
     <Layout
       tabs={tabs}