feat(docs-sidenav): support index pages in nav-data (#358)

* feat(docs-sidenav): support index pages in nav-data

* chore(docs-sidenav): improve path mismatch error message

* tests(docs-sidenav): fix error message check, test title

* test(docs-sidenav): format test to match inline snapshot style

* fix: move changes from server.js to appropriate module

* chore: add return types to functions

.changeset/chilled-items-wash.md

@@ -0,0 +1,5 @@
+---
+'@hashicorp/react-docs-sidenav': minor
+---
+
+Support empty paths for index pages.

.changeset/new-lamps-hear.md

@@ -0,0 +1,5 @@
+---
+'@hashicorp/react-docs-page': patch
+---
+
+Support possibility of index page being included in nav-data.

packages/docs-page/server/get-paths-from-nav-data.ts

@@ -2,7 +2,7 @@ import { NavNode } from '@hashicorp/react-docs-sidenav/types'
 
 import { DEFAULT_PARAM_ID } from './consts'
 
-export function getPathArraysFromNodes(navNodes: NavNode[]) {
+export function getPathArraysFromNodes(navNodes: NavNode[]): string[][] {
   const slugs: string[][] = navNodes.reduce((acc, navNode) => {
     // Individual items have a path, these should be added
     if ('path' in navNode) return acc.concat([navNode.path.split('/')])
@@ -18,13 +18,16 @@ export function getPathArraysFromNodes(navNodes: NavNode[]) {
 export function getPathsFromNavData(
   navDataResolved: NavNode[],
   paramId: string = DEFAULT_PARAM_ID
-) {
+): {
+  params: Record<string, string[]>
+}[] {
   //  Transform navigation data into path arrays
   const pagePathArrays = getPathArraysFromNodes(navDataResolved)
-  // Include an empty array for the "/" index page path
-  const allPathArrays = [[]].concat(pagePathArrays)
-  const paths = allPathArrays.map((p) => ({ params: { [paramId]: p } }))
-  return paths as {
-    params: Record<string, string[]>
-  }[]
+  // Ensure we include an empty array for the "/" index page path
+  // (may be included in nav-data, eg for Terraform, or may not, eg for all other sites)
+  const hasIndexPage = pagePathArrays.filter((p) => p == []).length > 0
+  if (!hasIndexPage) pagePathArrays.unshift([])
+  // Return the array of all page paths
+  const paths = pagePathArrays.map((p) => ({ params: { [paramId]: p } }))
+  return paths
 }

packages/docs-sidenav/fixtures/content/index.mdx

@@ -0,0 +1,16 @@
+---
+page_title: Index
+description: >-
+  This file is the index page
+---
+
+# Index Page
+
+Welcome to the introduction guide to HashiCorp Vault! This guide is the best
+place to get started with Vault. This guide covers what Vault is, what problems
+it can solve, how it compares to existing software, and contains a quick start
+for using Vault.
+
+If you are already familiar with the basics of Vault, the
+[documentation](/docs) provides a better reference guide for all
+available features as well as internals.

packages/docs-sidenav/fixtures/nav-data.json

@@ -1,4 +1,8 @@
 [
+  {
+    "title": "Overview",
+    "path": ""
+  },
   {
     "title": "What is Vault?",
     "path": "what-is-vault"

packages/docs-sidenav/index.js

@@ -189,7 +189,7 @@ function NavTree({ baseRoute, content }) {
       )
     }
     // Individual pages (leaf nodes)
-    if (item.path) {
+    if (typeof item.path == 'string') {
       return (
         <NavLeaf
           key={item.path}

packages/docs-sidenav/utils/flag-active-nodes.js

@@ -44,7 +44,7 @@ function addIsActiveToNode(navNode, currentPath, pathname) {
   }
   // If it's a node with a path value,
   // return true if the path is a match
-  if (navNode.path) {
+  if (typeof navNode.path == 'string') {
     const isActive = navNode.path === currentPath
     return { ...navNode, __isActive: isActive }
   }

packages/docs-sidenav/utils/validate-file-paths/index.js

@@ -17,7 +17,7 @@ async function validateNode(navNode, localDir) {
   // for Packer plugin documentation)
   if (navNode.remoteFile) return navNode
   // Handle local leaf nodes
-  if (navNode.path) {
+  if (typeof navNode.path == 'string') {
     const indexFilePath = path.join(navNode.path, 'index.mdx')
     const namedFilePath = `${navNode.path}.mdx`
     const hasIndexFile = fs.existsSync(

packages/docs-sidenav/utils/validate-route-structure/index.js

@@ -13,13 +13,6 @@ function validateBranchRoutes(navNodes, depth = 0) {
   const navNodesWithStacks = navNodes.map((navNode) => {
     // Handle leaf nodes - split their paths into a __stack
     if (typeof navNode.path !== 'undefined') {
-      if (navNode.path == '') {
-        throw new Error(
-          `Empty path value on NavLeaf. Path values must be non-empty strings. Node: ${JSON.stringify(
-            navNode
-          )}.`
-        )
-      }
       if (!navNode.title) {
         throw new Error(
           `Missing nav-data title. Please add a non-empty title to the node with the path "${navNode.path}".`
@@ -124,7 +117,9 @@ function validateBranchRoutes(navNodes, depth = 0) {
   // that don't share the same parent path.
   if (uniqueParents.length > 1) {
     throw new Error(
-      `Found mismatched paths at depth ${depth}: ${JSON.stringify(
+      `Found mismatched paths at depth ${depth}, with paths: ${JSON.stringify(
+        routePaths
+      )}. Implies mismatched parent directories: ${JSON.stringify(
         uniqueParents
       )}.`
     )

packages/docs-sidenav/utils/validate-route-structure/index.test.js

@@ -1,20 +1,6 @@
 import validateRouteStructure from './'
 
-describe('<DocsSidenav /> - validate-file-paths', () => {
-  it("throws an error if a NavLeaf's path is an empty string", () => {
-    const navData = [
-      {
-        title: 'Whoops I Left The Path Empty',
-        path: '',
-      },
-    ]
-    expect(() =>
-      validateRouteStructure(navData)
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"Empty path value on NavLeaf. Path values must be non-empty strings. Node: {\\"title\\":\\"Whoops I Left The Path Empty\\",\\"path\\":\\"\\"}."`
-    )
-  })
-
+describe('<DocsSidenav /> - validate-route-structure', () => {
   it("throws an error if a NavLeaf's path is nested at the wrong depth", () => {
     const navData = [
       {
@@ -85,7 +71,7 @@ describe('<DocsSidenav /> - validate-file-paths', () => {
     expect(() =>
       validateRouteStructure(navData)
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Found mismatched paths at depth 1: [\\"directory\\",\\"another-directory\\"]."`
+      `"Found mismatched paths at depth 1, with paths: [\\"directory\\",\\"directory/some-file\\",\\"another-directory/another-file\\"]. Implies mismatched parent directories: [\\"directory\\",\\"another-directory\\"]."`
     )
   })