@hashicorp/react-components 0.0.0

package/packages/docs-page/package-lock.json

@@ -0,0 +1,138 @@
+{
+	"name": "@hashicorp/react-docs-page",
+	"version": "8.0.0",
+	"lockfileVersion": 1,
+	"requires": true,
+	"dependencies": {
+		"@hashicorp/react-content": {
+			"version": "6.0.0",
+			"resolved": "https://registry.npmjs.org/@hashicorp/react-content/-/react-content-6.0.0.tgz",
+			"integrity": "sha512-AYIe6tcOxlKPe5Sq89o/Vk0rGE6Z1dCzf+N3ynECTh5L2A1zusf9xeM659QEh/edE/Ll9EBBLmq49sQXLNDxTw=="
+		},
+		"@hashicorp/react-docs-sidenav": {
+			"version": "6.0.0",
+			"resolved": "https://registry.npmjs.org/@hashicorp/react-docs-sidenav/-/react-docs-sidenav-6.0.0.tgz",
+			"integrity": "sha512-NUV3PjmuryvmcOj9WO4G3hrSe07uIgbghYYGhI9XQmxYo0gAXp62IlN/x6f1NNkC4OGd55+mzcgTwlUt+hv1sQ==",
+			"requires": {
+				"@hashicorp/react-link-wrap": "^0.0.3",
+				"fuzzysearch": "1.0.3"
+			}
+		},
+		"@hashicorp/react-head": {
+			"version": "1.1.6",
+			"resolved": "https://registry.npmjs.org/@hashicorp/react-head/-/react-head-1.1.6.tgz",
+			"integrity": "sha512-5r2g9XNO6YHhl9/4GniiN1Reqs/mOu/7rUML+JQsN2qe7V3libr+cLa+iSYK7+pLmRlnc+Uwk7JwPPPJHVj5bA=="
+		},
+		"@hashicorp/react-link-wrap": {
+			"version": "0.0.3",
+			"resolved": "https://registry.npmjs.org/@hashicorp/react-link-wrap/-/react-link-wrap-0.0.3.tgz",
+			"integrity": "sha512-BLH7SLMJZee8md+YU7seiOh0zpa7y8sEhEATYpK2ieFanXAQEgU58lNSC/V3ZdkSXrfyplftYuOj0E3APtE1pg==",
+			"requires": {
+				"is-absolute-url": "^3.0.3"
+			}
+		},
+		"argparse": {
+			"version": "1.0.10",
+			"resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz",
+			"integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==",
+			"requires": {
+				"sprintf-js": "~1.0.2"
+			}
+		},
+		"esprima": {
+			"version": "4.0.1",
+			"resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
+			"integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="
+		},
+		"extend-shallow": {
+			"version": "2.0.1",
+			"resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+			"integrity": "sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8=",
+			"requires": {
+				"is-extendable": "^0.1.0"
+			}
+		},
+		"fs-exists-sync": {
+			"version": "0.1.0",
+			"resolved": "https://registry.npmjs.org/fs-exists-sync/-/fs-exists-sync-0.1.0.tgz",
+			"integrity": "sha1-mC1ok6+RjnLQjeyehnP/K1qNat0="
+		},
+		"fuzzysearch": {
+			"version": "1.0.3",
+			"resolved": "https://registry.npmjs.org/fuzzysearch/-/fuzzysearch-1.0.3.tgz",
+			"integrity": "sha1-3/yA9tawQiPyImqnndGUIxCW0Ag="
+		},
+		"gray-matter": {
+			"version": "4.0.2",
+			"resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-4.0.2.tgz",
+			"integrity": "sha512-7hB/+LxrOjq/dd8APlK0r24uL/67w7SkYnfwhNFwg/VDIGWGmduTDYf3WNstLW2fbbmRwrDGCVSJ2isuf2+4Hw==",
+			"requires": {
+				"js-yaml": "^3.11.0",
+				"kind-of": "^6.0.2",
+				"section-matter": "^1.0.0",
+				"strip-bom-string": "^1.0.0"
+			}
+		},
+		"is-absolute-url": {
+			"version": "3.0.3",
+			"resolved": "https://registry.npmjs.org/is-absolute-url/-/is-absolute-url-3.0.3.tgz",
+			"integrity": "sha512-opmNIX7uFnS96NtPmhWQgQx6/NYFgsUXYMllcfzwWKUMwfo8kku1TvE6hkNcH+Q1ts5cMVrsY7j0bxXQDciu9Q=="
+		},
+		"is-extendable": {
+			"version": "0.1.1",
+			"resolved": "https://registry.npmjs.org/is-extendable/-/is-extendable-0.1.1.tgz",
+			"integrity": "sha1-YrEQ4omkcUGOPsNqYX1HLjAd/Ik="
+		},
+		"js-yaml": {
+			"version": "3.14.0",
+			"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.0.tgz",
+			"integrity": "sha512-/4IbIeHcD9VMHFqDR/gQ7EdZdLimOvW2DdcxFjdyyZ9NsbS+ccrXqVWDtab/lRl5AlUqmpBx8EhPaWR+OtY17A==",
+			"requires": {
+				"argparse": "^1.0.7",
+				"esprima": "^4.0.0"
+			}
+		},
+		"kind-of": {
+			"version": "6.0.3",
+			"resolved": "https://registry.npmjs.org/kind-of/-/kind-of-6.0.3.tgz",
+			"integrity": "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="
+		},
+		"line-reader": {
+			"version": "0.4.0",
+			"resolved": "https://registry.npmjs.org/line-reader/-/line-reader-0.4.0.tgz",
+			"integrity": "sha1-F+RIGNoKwzVnW6MAlU+U72cOZv0="
+		},
+		"picomatch": {
+			"version": "2.2.2",
+			"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.2.2.tgz",
+			"integrity": "sha512-q0M/9eZHzmr0AulXyPwNfZjtwZ/RBZlbN3K3CErVrk50T2ASYI7Bye0EvekFY3IP1Nt2DHu0re+V2ZHIpMkuWg=="
+		},
+		"readdirp": {
+			"version": "3.5.0",
+			"resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.5.0.tgz",
+			"integrity": "sha512-cMhu7c/8rdhkHXWsY+osBhfSy0JikwpHK/5+imo+LpeasTF8ouErHrlYkwT0++njiyuDvc7OFY5T3ukvZ8qmFQ==",
+			"requires": {
+				"picomatch": "^2.2.1"
+			}
+		},
+		"section-matter": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/section-matter/-/section-matter-1.0.0.tgz",
+			"integrity": "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==",
+			"requires": {
+				"extend-shallow": "^2.0.1",
+				"kind-of": "^6.0.0"
+			}
+		},
+		"sprintf-js": {
+			"version": "1.0.3",
+			"resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz",
+			"integrity": "sha1-BOaSb2YolTVPPdAVIDYzuFcpfiw="
+		},
+		"strip-bom-string": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/strip-bom-string/-/strip-bom-string-1.0.0.tgz",
+			"integrity": "sha1-5SEekiQ2n7uB1jOi8ABE3IztrZI="
+		}
+	}
+}

package/packages/docs-page/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hashicorp/react-docs-page",
+  "description": "Create a Hashicorp branded docs page in NextJS projects.",
+  "version": "8.0.0-canary.1",
+  "author": "Hashicorp",
+  "contributors": [
+    "Jeff Escalante"
+  ],
+  "dependencies": {
+    "@hashicorp/react-content": "^6.0.0",
+    "@hashicorp/react-docs-sidenav": "^6.0.0",
+    "@hashicorp/react-head": "^1.1.6",
+    "fs-exists-sync": "0.1.0",
+    "gray-matter": "4.0.2",
+    "js-yaml": "3.14.0",
+    "line-reader": "0.4.0",
+    "readdirp": "3.5.0"
+  },
+  "license": "MPL-2.0",
+  "peerDependencies": {
+    "@hashicorp/nextjs-scripts": "13.0.0",
+    "next-mdx-remote": "1.0.0",
+    "react": "^16.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/docs-page/props.js

@@ -0,0 +1,59 @@
+module.exports = {
+  product: {
+    type: 'object',
+    description: 'Name and slug of the product this page is being rendered for',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Human-readable proper case product name',
+      },
+      slug: {
+        type: 'string',
+        description: 'HashiCorp product slug',
+        control: { type: 'select' },
+        options: [
+          'terraform',
+          'vault',
+          'nomad',
+          'consul',
+          'packer',
+          'vagrant',
+          'red',
+          'blue',
+        ],
+      },
+    },
+  },
+  subpath: {
+    type: 'string',
+    description:
+      'The path this page is rendering under, for example "docs" or "api-docs". Passed directly to the `category` prop of `@hashicorp/react-docs-sidenav`',
+  },
+  order: {
+    type: 'object',
+    description:
+      'Pass in the export of a `data/xxx-navigation.js` file, this is the user-defined navigation order and structure. Passed directly to the `order` prop to `@hashicorp/react-docs-sidenav` - see that component for details on object structure.',
+  },
+  additionalComponents: {
+    type: 'object',
+    description:
+      'Object containing additional components to be made available within mdx pages. Uses the format { [key]: Component }, for example, `{ TestComponent: () => <p>hello world</p> }`',
+  },
+  showEditPage: {
+    type: 'boolean',
+    description:
+      'if true, an "edit this page" link will appear on the bottom right',
+    default: true,
+  },
+  mainBranch: {
+    type: 'string',
+    description:
+      'The default branch of the project being documented, typically either "master" or "main". Used for the `showEditPage` prop',
+    default: 'main',
+  },
+  staticProps: {
+    type: 'object',
+    description:
+      'Directly pass the return value of `server/generateStaticProps` in here.',
+  },
+}

package/packages/docs-page/server.js

@@ -0,0 +1,137 @@
+import fs from 'fs'
+import path from 'path'
+import existsSync from 'fs-exists-sync'
+import readdirp from 'readdirp'
+import lineReader from 'line-reader'
+import matter from 'gray-matter'
+import { safeLoad } from 'js-yaml'
+import renderToString from 'next-mdx-remote/render-to-string'
+import markdownDefaults from '@hashicorp/nextjs-scripts/markdown'
+import generateComponents from './components'
+
+export async function generateStaticPaths(subpath) {
+  const paths = await getStaticMdxPaths(
+    path.join(process.cwd(), 'content', subpath)
+  )
+
+  return { paths, fallback: false }
+}
+
+export async function generateStaticProps(subpath, productName, params) {
+  const docsPath = path.join(process.cwd(), 'content', subpath)
+  const pagePath = params.page ? params.page.join('/') : '/'
+
+  // get frontmatter from all other pages in the category, for the sidebar
+  const allFrontMatter = await fastReadFrontMatter(docsPath)
+
+  // render the current page path markdown
+  const { mdxSource, frontMatter, filePath } = await renderPageMdx(
+    docsPath,
+    pagePath,
+    generateComponents(productName)
+  )
+
+  return {
+    props: {
+      data: allFrontMatter.map((p) => {
+        p.__resourcePath = `${subpath}/${p.__resourcePath}`
+        return p
+      }),
+      mdxSource,
+      frontMatter,
+      filePath,
+      pagePath: `/${subpath}/${pagePath}`,
+    },
+  }
+}
+
+async function getStaticMdxPaths(root) {
+  const files = await readdirp.promise(root, { fileFilter: ['*.mdx'] })
+
+  return files.map(({ path: p }) => {
+    return {
+      params: {
+        page: p
+          .replace(/\.mdx$/, '')
+          .split('/')
+          .filter((p) => p !== 'index'),
+      },
+    }
+  })
+}
+
+async function renderPageMdx(root, pagePath, components) {
+  // get the page being requested - figure out if its index page or leaf
+  // prefer leaf if both are present
+  const leafPath = path.join(root, `${pagePath}.mdx`)
+  const indexPath = path.join(root, `${pagePath}/index.mdx`)
+  let page, filePath
+
+  if (existsSync(leafPath)) {
+    page = fs.readFileSync(leafPath, 'utf8')
+    filePath = leafPath
+  } else if (existsSync(indexPath)) {
+    page = fs.readFileSync(indexPath, 'utf8')
+    filePath = indexPath
+  } else {
+    // NOTE: if we decide to let docs pages render dynamically, we should replace this
+    // error with a straight 404, at least in production.
+    throw new Error(
+      `We went looking for "${leafPath}" and "${indexPath}" but neither one was found.`
+    )
+  }
+
+  const { data: frontMatter, content } = matter(page)
+  const mdxSource = await renderToString(content, {
+    mdxOptions: markdownDefaults({
+      resolveIncludes: path.join(process.cwd(), 'content/partials'),
+    }),
+    components,
+  })
+
+  return {
+    mdxSource,
+    frontMatter,
+    filePath: filePath.replace(`${root}/`, ''),
+  }
+}
+
+async function fastReadFrontMatter(p) {
+  const fm = []
+  for await (const entry of readdirp(p, { fileFilter: '*.mdx' })) {
+    let lineNum = 0
+    const content = []
+    fm.push(
+      new Promise((resolve, reject) => {
+        lineReader.eachLine(
+          entry.fullPath,
+          (line) => {
+            // if it has any content other than `---`, the file doesn't have front matter, so we close
+            if (lineNum === 0 && !line.match(/^---$/)) {
+              console.warn(
+                `WARNING: The file "${entry.path}" is missing front matter. Please add front matter to ensure the file's metadata is properly populated.`
+              )
+              content.push('---')
+              content.push('page_title: "ERROR: Missing Frontmatter"')
+              return false
+            }
+            // if it's not the first line and we have a bottom delimiter, exit
+            if (lineNum !== 0 && line.match(/^---$/)) return false
+            // now we read lines until we match the bottom delimiters
+            content.push(line)
+            // increment line number
+            lineNum++
+          },
+          (err) => {
+            if (err) return reject(err)
+            content.push(`__resourcePath: "${entry.path}"`)
+            resolve(safeLoad(content.slice(1).join('\n')), {
+              filename: entry.fullPath,
+            })
+          }
+        )
+      })
+    )
+  }
+  return Promise.all(fm)
+}

package/packages/docs-page/style.css

@@ -0,0 +1,120 @@
+#p-docs {
+  & .content-wrap {
+    display: flex;
+    flex-direction: column;
+    flex-wrap: wrap;
+    flex: 1 0 auto;
+    position: relative;
+    width: 100%;
+
+    @media (min-width: 940px) {
+      flex-direction: row;
+      margin-bottom: 24px;
+      margin-top: 72px;
+    }
+  }
+
+  & #inner {
+    margin: 64px 0;
+    overflow: auto;
+    width: 100%;
+
+    @media (min-width: 940px) {
+      flex: 1;
+      margin: 0;
+    }
+
+    & .g-content {
+      @media (max-width: 939px) {
+        padding-left: 0;
+        padding-right: 0;
+      }
+
+      & > h1:first-child {
+        margin-top: 0;
+
+        &.has-jts {
+          margin-bottom: 10px;
+        }
+      }
+    }
+
+    & .g-section-header {
+      margin-bottom: 100px;
+    }
+
+    /* TODO: this should be applied in global styles, temporary override here */
+    & pre,
+    & code {
+      font-size: 0.875em;
+    }
+
+    & pre code {
+      font-size: 1em;
+    }
+  }
+
+  & #edit-this-page {
+    display: flex;
+    justify-content: flex-end;
+    margin-bottom: 48px;
+
+    & a {
+      align-items: center;
+      color: var(--gray-1);
+      display: flex;
+      opacity: 0.5;
+      padding-right: 32px;
+      transition: opacity 0.4s ease;
+
+      &:hover {
+        opacity: 1;
+      }
+
+      & > img {
+        height: 22px;
+        margin-right: 9px;
+        width: 23px;
+      }
+    }
+  }
+
+  & table tr.warning td {
+    background: #fcf8e3;
+  }
+
+  & #jump-to-section {
+    cursor: pointer;
+    display: inline-block;
+    margin-bottom: 20px;
+    margin-left: 5px;
+    position: relative;
+    user-select: none;
+    z-index: 3;
+
+    & .trigger {
+      align-items: center;
+      display: flex;
+    }
+
+    & svg {
+      margin-left: 5px;
+    }
+
+    & .dropdown {
+      background: white;
+      border-radius: 3px;
+      box-shadow: 0 5px 8px rgba(0, 0, 0, 0.25);
+      display: none;
+      margin: 10px 0 0 0;
+      padding: 0 0 0 30px;
+      position: absolute;
+      width: 500px;
+      z-index: 2;
+
+      &.active {
+        display: block;
+      }
+    }
+  }
+}

package/packages/docs-page/temporary_jump-to-section.js

@@ -0,0 +1,64 @@
+// This is terrible, very non-idiomatic code. It is here temporarily to enable this feature
+// while the team works on a more permanent solution. Please do not ever write code like this.
+// Ticket to fix this: https://app.asana.com/0/1100423001970639/1160656182754009
+export default function temporary_injectJumpToSection(node) {
+  const root = node.children[0]
+  const firstH1 = root.querySelector('h1')
+  const otherH2s = [].slice.call(root.querySelectorAll('h2')) // NodeList -> array
+
+  // if there's no h1 or no 3 h2s, don't render jump to section
+  if (!firstH1) return
+  if (otherH2s.length < 1) return
+
+  const headlines = otherH2s.map((h2) => {
+    // slice removes the anchor link character
+    return {
+      id: h2.querySelector('.__target-h').id,
+      text: h2.innerText.slice(1),
+    }
+  })
+
+  // build the html
+  const html = `
+    <span class="trigger g-type-label">
+      Jump to Section
+      <svg width="9" height="5" xmlns="http://www.w3.org/2000/svg"><path d="M8.811 1.067a.612.612 0 0 0 0-.884.655.655 0 0 0-.908 0L4.5 3.491 1.097.183a.655.655 0 0 0-.909 0 .615.615 0 0 0 0 .884l3.857 3.75a.655.655 0 0 0 .91 0l3.856-3.75z" fill-rule="evenodd"/></svg>
+    </span>
+    <ul class="dropdown">
+      ${headlines
+        .map((h) => `<li><a href="#${h.id}">${h.text}</a></li>`)
+        .join('')}
+    </ul>`
+  const el = document.createElement('div')
+  el.innerHTML = html
+  el.id = 'jump-to-section'
+
+  // attach event listeners to make the dropdown work
+  const trigger = el.querySelector('.trigger')
+  const dropdown = el.querySelector('.dropdown')
+  const body = document.body
+  const triggerEvent = (e) => {
+    e.stopPropagation()
+    dropdown.classList.toggle('active')
+  }
+  const clickOutsideEvent = () => dropdown.classList.remove('active')
+  const clickInsideDropdownEvent = (e) => e.stopPropagation()
+  trigger.addEventListener('click', triggerEvent)
+  body.addEventListener('click', clickOutsideEvent)
+  dropdown.addEventListener('click', clickInsideDropdownEvent)
+
+  // inject the html after the first h1
+  firstH1.parentNode.insertBefore(el, firstH1.nextSibling)
+
+  // adjust the h1 margin
+  firstH1.classList.add('has-jts')
+
+  // cleanup function removes listeners on unmount
+  return function cleanup() {
+    trigger.removeEventListener('click', triggerEvent)
+    body.removeEventListener('click', clickOutsideEvent)
+    dropdown.removeEventListener('click', clickInsideDropdownEvent)
+    firstH1.classList.remove('has-jts')
+    el.remove()
+  }
+}