Add side nav tree - Githubissues

Summary

This is an extension of https://github.com/carbon-design-system/gatsby-theme-carbon/issues/1362 that should be completed together.

The current side nav is limited by one level of nesting. This has resulted in a cluttered side nav, and an overly aggressive use of page tabs.

The Carbon core team built an entirely new way to do this in Carbon Platform by taking the (now stable) TreeView component (part of Carbon v11):

https://react.carbondesignsystem.com/?path=/docs/components-treeview--overview

And then theming and customizing it to work as a side nav with multiple levels of nesting. The Carbon Platform doesn't have an example of level two nesting, but here's an example from the design spec:

Justification

This will allow much needed UX and IA improvements for the various Carbon local system (PAL) websites that are build with the Carbon Gatsby Theme.

Desired UX and success metrics

Match the coded TreeNav component used in Carbon Platform: https://next.carbondesignsystem.com

Here's the design spec used to build Carbon Platform, in case a bug is identified in Carbon Platform: https://www.figma.com/file/UkKF0SLT3qUmGoXQFVKtXT/RL_Library_Navigation?type=design&node-id=0-1&mode=design&t=unaj7OSZxa6uc7Zp-0

Must-have functionality

This is the current nav data model:

- title: Menu
  pages:
    - title: Page 1
      path: /menu/Page-1
    - title: Page 2
      path: /menu/Page-2
- title: Single Page
  pages:
    - path: /single-page

I'm thinking we'd want to support a second level of links with a YAML structure like:

- title: Menu
  pages:
    - title: Page 1
      path: /menu/Page-1
    - title: Page 2
      pages:
        - title: Level two page
          path: /menu/page-2/level-two-page
        - title: Another level two page
          path: /menu/page-2/another-level-two-page
- title: Single Page
  pages:
    - path: /single-page

Like the side nav heading issue, any changes to the nav data should included updated documentation.

Both of these issues would needed to be completed without breaking changes. Because these enhancements only add to the nav data model, that should be possible.

Development considerations

Here is the Carbon Platform source for NavTree that could be lifted and shifted. Because the nav data model is different, this requires more than a copy paste job. The styling overrides could be used directly, but the logic to parse the nav data will have to be different.

https://github.com/carbon-design-system/carbon-platform/tree/main/services/web-app/components/nav-tree

Because the latest version of the Gatsby theme uses Carbon v11, this should be possible without having to update any Carbon versions.

Specific timeline issues / requests

N/A

Available extra resources

@glapadre might consider contributing this enhancement.

### Tasks
- [ ] Single level of nesting should remain the same as current navs
- [ ] Tree view should only apply if there are multiple levels of nesting (update the markup)
- [ ] Visually should remain the same

carbon-design-system / gatsby-theme-carbon

Add side nav tree #1363