@hashicorp/react-components 0.0.0

package/packages/search/README.md

@@ -0,0 +1,188 @@
+# @hashicorp/react-search
+
+## Props
+
+### renderHitContent
+
+> `function` | `({ hit: object, Highlight: React.Node }) => React.Component` | _Required_
+
+A render function whose result is used to display each query "hit"
+
+**Params**
+
+| Property  | Type         | Description                                                                         |
+|-----------|--------------|-------------------------------------------------------------------------------------|
+| hit       | `object`     | https://www.algolia.com/doc/api-reference/widgets/highlight/react/#widget-param-hit |
+| Highlight | `React.Node` | https://www.algolia.com/doc/api-reference/widgets/highlight/react/                  |
+
+### resolveHitLink
+
+> `function` | | `( hit: object ) => NextLinkProps` | _Optional_ | **Default:** (hit) => ({ href:`/${hit.objectID}` })
+
+A function whose return value is spread as props to `next/link`.
+For more information about the available props, reference the next/link documentation: https://nextjs.org/docs/api-reference/next/link
+
+**Params**
+
+| Property | Type     | Description                                                                         |
+|----------|----------|-------------------------------------------------------------------------------------|
+| hit      | `object` | https://www.algolia.com/doc/api-reference/widgets/highlight/react/#widget-param-hit |
+
+### placeholder
+
+> `string` | _Optional_ | **Default:** `Search`
+
+## Usage
+
+```jsx
+import Search from '@hashicorp/react-search'
+
+function SearchBar() {
+  return (
+    <Search
+      renderHitContent={({ hit, Highlight }) => <div>...</div>}
+      resolveHitLink={(hit) => ({ href: { pathname: `/${hit.objectID}`, query: { id: hit.__queryID} } })}
+      placeholder="Search documentation"
+    />
+}
+```
+
+### Environment Variables
+
+This component relies on the presence of the following environment variables to be available client side:
+
+```text
+NEXT_PUBLIC_ALGOLIA_APP_ID
+NEXT_PUBLIC_ALGOLIA_SEARCH_ONLY_API_KEY
+NEXT_PUBLIC_ALGOLIA_INDEX
+```
+
+### React
+
+To use the primary `<Search />` component, ensure it exists as a child of the `<SearchProvider />` component. For example:
+
+**App.jsx**
+
+```jsx
+import Search, { SearchProvider } from '@hashicorp/react-search'
+
+function App() {
+  return (
+    <>
+      <SearchProvider>
+        <Search
+          renderHitContent={({hit, Highlight}) => (
+            <span className="name">
+              <Highlight attribute="name" hit={hit} tagName="span" />
+            </span>
+          )}
+          resolveHitLink={(hit) => ({ href: `/${hit.objectID}` })}
+        />
+        <ComponentA>
+        <ComponentB>
+      </SearchProvider>
+      <ComponentC__WithoutSearchContext>
+    </>
+  )
+}
+```
+
+Any child component of `<SearchProvider />` can utilize the provided `useSearch()` hook and access search-specific information. For example:
+
+```jsx
+import { useSearch } from '@hashicorp/react-search'
+
+function ComponentA() {
+  const { query } = useSearch()
+
+  return <code>Search query: {query}</code>
+}
+```
+
+## useSearch()
+
+`useSearch()` exposes the following values:
+
+- `client` (`object`) - Initialized Algolia client
+- `indexName` (`string`) - The name of the Algolia index that search is performed upon
+- `initAlgoliaInsights` (`function`) - Required to initialize Algolia
+- `isCancelled` (`boolean`) - Indicates if search is currently cancelled or not
+- `logClick` (`function`) - Fires an analytics event via the `search-insights` package
+- `query` (`string`) - Current search query
+- `setIsCancelled` (`function`) - Setter function that updates the search cancel state
+- `setQuery` (`function`) - Setter function that updates the search query
+
+
+## Tools
+
+This package includes a `tools.js` file that includes Algolia-related Node.js scripts
+
+### Usage
+
+```js
+const { indexDocsContent, indexContent } = require('@hashicorp/react-search/tools')
+/* It's worth noting that you'd only want to use *one* of the two exported functions */
+```
+
+#### indexDocsContent
+> `function` | `(config: object)`
+This specific helper function is designed specifically for perfoming search indexing on our various product sites' documentation pages.
+
+##### config.algoliaConfig: { appId: string, apiKey: string, index: string }
+
+Algolia-related configuration
+
+_Default_:
+```js
+{
+  apiKey: process.env.ALGOLIA_API_KEY,
+  appId: process.env.NEXT_PUBLIC_ALGOLIA_APP_ID,
+  index: process.env.NEXT_PUBLIC_ALGOLIA_INDEX,
+}
+```
+
+##### config.contentDir: string
+
+Path to directory that contains the content to be indexed by Algolia
+
+_Default_: `path.join(__dirname, 'pages')`
+
+##### config.filesPattern: string
+
+[minimatch](https://github.com/isaacs/minimatch)-style string to be performed within `config.contentDir`. The results of this pattern match will determine which files to index.
+
+_Default_: `'**/*.mdx'`
+
+##### config.globOptions: { [k:string]: any }
+
+Additional options to include to the glob match. Available options [here](https://github.com/isaacs/node-glob#options)
+
+_Default_: `{ ignore: path.join(config.contentDir, 'partials/**/*') }`
+
+##### config.frontmatterKeys: string[]
+
+Assuming your search-indexed content includes [frontmatter](https://jekyllrb.com/docs/front-matter/), the keys included in this `array` will be included as search criteria.
+
+_Default_: `['page_title', 'description']`
+
+
+#### indexContent
+> `function` | `(config: object)`
+This generic helper function allows for custom Algolia indexing
+
+##### config.algoliaConfig: { appId: string, apiKey: string, index: string }
+
+Algolia-related configuration
+
+_Default_:
+```js
+{
+  apiKey: process.env.ALGOLIA_API_KEY,
+  appId: process.env.NEXT_PUBLIC_ALGOLIA_APP_ID,
+  index: process.env.NEXT_PUBLIC_ALGOLIA_INDEX,
+}
+```
+
+##### config.getSearchObjects: () => any
+
+This function should return an array of objects that will get passed to Algolias [`partialUpdateObjects`](https://www.algolia.com/doc/api-reference/api-methods/partial-update-objects/) function

package/packages/search/hits.js

@@ -0,0 +1,196 @@
+import { forwardRef, useEffect, useRef, useState } from 'react'
+import Link from 'next/link'
+import { Highlight, connectHits } from 'react-instantsearch-dom'
+import generateSlug from '@hashicorp/remark-plugins/generate_slug'
+import InlineSvg from '@hashicorp/react-inline-svg'
+import SearchLegend from './legend'
+import { useSearch } from './provider'
+import IconReturn from './img/return.svg.js'
+
+function Hits({
+  /* Props provided from connector */
+  hits,
+  /* Props passed explicity */
+  handleEscape,
+  renderHitContent,
+  resolveHitLink,
+  query,
+  setCancelled,
+}) {
+  const selectedHit = useRef(null)
+  const [hitsTabIndex, setHitsTabIndex] = useState(null)
+
+  useEffect(() => {
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [hitsTabIndex])
+
+  useEffect(() => {
+    if (selectedHit?.current) scrollToActive(selectedHit.current)
+  }, [hitsTabIndex])
+
+  function onKeyDown(e) {
+    switch ([e.ctrlKey, e.keyCode].join(',')) {
+      // [Enter]
+      case 'false,13':
+        return handleEnter(e)
+      // [Escape]
+      case 'false,27':
+        setHitsTabIndex(null)
+        return handleEscape()
+      // [ArrowDown]
+      // [Ctrl-n]
+      case 'false,40':
+      case 'true,78':
+        if (!hitsTabIndex) {
+          setHitsTabIndex(0)
+          scrollToActive()
+        }
+        return incrementTabIndex()
+      // [ArrowUp]
+      // [Ctrl-p]
+      case 'false,38':
+      case 'true,80':
+        e.preventDefault()
+        return decrementTabIndex()
+    }
+  }
+
+  function handleEnter(e) {
+    e.preventDefault()
+    selectedHit.current?.click()
+  }
+
+  function incrementTabIndex() {
+    let startIndex = hitsTabIndex || 0
+    const nextIndex = startIndex + 1
+    if (nextIndex > hits.length) return setHitsTabIndex(1)
+    setHitsTabIndex(nextIndex)
+  }
+
+  function decrementTabIndex() {
+    let startIndex = hitsTabIndex || 0
+    const nextIndex = startIndex - 1
+    if (nextIndex < 1) return setHitsTabIndex(hits.length)
+    setHitsTabIndex(nextIndex)
+  }
+
+  function scrollToActive(el) {
+    if (!el) return
+    el.scrollIntoView({
+      behavior: 'smooth',
+      block: 'nearest',
+      inline: 'nearest',
+    })
+  }
+
+  return (
+    <div className="c-hits">
+      {hits.length === 0 ? (
+        <div className="no-hits">
+          <span className="title">{`No results for ${query}...`}</span>
+          <span className="message">
+            Search tips: some terms require an exact match. Try typing the
+            entire term, or use a different word or phrase.
+          </span>
+        </div>
+      ) : (
+        <div className="hits">
+          <SearchLegend />
+          <ul className="hits-list">
+            {hits.map((hit) => (
+              <Hit
+                key={hit.objectID}
+                closeSearchResults={() => setCancelled(true)}
+                hit={hit}
+                renderHitContent={renderHitContent}
+                resolveHitLink={resolveHitLink}
+                {...(hitsTabIndex === hit.__position && {
+                  className: 'active',
+                  ref: selectedHit,
+                })}
+              />
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default connectHits(Hits)
+
+/* eslint-disable react/display-name */
+
+//  we need an `a` tag that also has a click handler
+//  next/link passes a click handler to its child; so in order to merge ours in, we need this syntax
+//  ref: https://github.com/zeit/next.js/#with-link
+
+const LinkWithClick = forwardRef(({ children, ...props }, ref) => (
+  <a {...props} ref={ref}>
+    {children}
+  </a>
+))
+
+const Hit = forwardRef(
+  (
+    {
+      className = '',
+      closeSearchResults,
+      hit,
+      renderHitContent,
+      resolveHitLink,
+    },
+    ref
+  ) => {
+    const { logClick, setQuery } = useSearch()
+    let hitLink = resolveHitLink
+      ? resolveHitLink(hit)
+      : { href: `/${hit.objectID}` }
+
+    // We append an associated heading slug to hitLink.href if and only if the search result matches one heading
+    // and does not match either description or page title criteria
+    if (
+      hit?._highlightResult?.description?.matchLevel === 'none' &&
+      hit?._highlightResult?.page_title?.matchLevel === 'none'
+    ) {
+      const matchedHeading = hit.headings.filter((heading, idx) => {
+        return hit?._highlightResult?.headings[idx]?.matchLevel !== 'none'
+      })
+
+      if (matchedHeading.length === 1) {
+        hitLink.href =
+          typeof hitLink.href === 'object'
+            ? { ...hitLink.href, hash: generateSlug(matchedHeading[0]) }
+            : { pathname: hitLink.href, hash: generateSlug(matchedHeading[0]) }
+      }
+    }
+
+    const handleClick = () => {
+      logClick(hit)
+      closeSearchResults()
+      setQuery('')
+    }
+
+    return (
+      <li className="hit-item">
+        <Link {...hitLink} passHref>
+          <LinkWithClick
+            ref={ref}
+            className={`hit-link-wrapper ${className}`}
+            onClick={handleClick}
+          >
+            <div className="hit">
+              <div className="hit-content">
+                {renderHitContent({ hit, Highlight })}
+              </div>
+              <InlineSvg className={`icon-return`} src={IconReturn} />
+            </div>
+          </LinkWithClick>
+        </Link>
+      </li>
+    )
+  }
+)
+
+/* eslint-enable */

package/packages/search/img/return.svg.js

@@ -0,0 +1 @@
+export default `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M17 7v5a1 1 0 01-1 1H7.5" stroke="#76767D" stroke-linecap="round"/><path d="M10 10l-3 3 3 3" stroke="#76767D" stroke-linecap="round" stroke-linejoin="round"/></svg>`

package/packages/search/img/search-legend-enter.svg.js

@@ -0,0 +1 @@
+export default `<svg width="61" height="24" fill="none" xmlns="http://www.w3.org/2000/svg"><g opacity=".75"><rect x=".5" y=".5" width="60" height="23" rx=".5" stroke="#DCDDE0"/><path d="M11.252 16.132c1.44 0 2.4-.852 2.58-2.028h-1.2c-.276.792-.996.924-1.38.924-.948 0-1.572-.6-1.572-1.584v-.012h4.248c.144-1.98-.864-3.504-2.712-3.504-1.704 0-2.856 1.26-2.856 3.12 0 1.932 1.14 3.084 2.892 3.084zm-1.536-3.816c.048-.756.66-1.284 1.464-1.284.804 0 1.368.528 1.404 1.284H9.716zM15.085 16h1.272v-3.024c0-1.236.708-1.992 1.5-1.992.672 0 1.188.42 1.188 1.476V16h1.38v-3.684c0-2.028-1.44-2.472-2.268-2.472-.972 0-1.572.588-1.8.912V10h-1.272v6zm8.523 0h1.14l.012-1.128h-.816c-.576 0-.732-.192-.732-.792v-3h1.536V10h-1.536V8.08h-1.248V10h-.936v1.08h.936v3.324c0 .936.684 1.596 1.644 1.596zm4.402.132c1.44 0 2.4-.852 2.58-2.028h-1.2c-.276.792-.996.924-1.38.924-.948 0-1.572-.6-1.572-1.584v-.012h4.248c.144-1.98-.864-3.504-2.712-3.504-1.704 0-2.856 1.26-2.856 3.12 0 1.932 1.14 3.084 2.892 3.084zm-1.536-3.816c.048-.756.66-1.284 1.464-1.284.804 0 1.368.528 1.404 1.284h-2.868zM31.843 16h1.236v-3.036c0-1.476.935-1.74 1.751-1.728h.205V9.904h-.276c-1.14 0-1.56.6-1.68.828V10h-1.237v6z" fill="#76767D"/><path d="M54 7v5a1 1 0 01-1 1h-8.5" stroke="#76767D" stroke-linecap="round"/><path d="M47 10l-3 3 3 3" stroke="#76767D" stroke-linecap="round" stroke-linejoin="round"/></g></svg>`

package/packages/search/img/search-legend-escape.svg.js

@@ -0,0 +1 @@
+export default `<svg width="36" height="24" fill="none" xmlns="http://www.w3.org/2000/svg"><path opacity=".75" d="M11.703 16.143c1.56 0 2.6-.923 2.795-2.197h-1.3c-.299.858-1.079 1.001-1.495 1.001-1.027 0-1.703-.65-1.703-1.716v-.013h4.602c.156-2.145-.936-3.796-2.938-3.796-1.846 0-3.094 1.365-3.094 3.38 0 2.093 1.235 3.341 3.133 3.341zm-1.664-4.134c.052-.819.715-1.391 1.586-1.391.871 0 1.482.572 1.521 1.391H10.04zm8.091 4.134c1.21 0 2.535-.754 2.535-2.106 0-1.001-.598-1.729-2.626-1.976-.806-.104-1.105-.429-1.105-.78 0-.481.546-.689 1.053-.689.364 0 1.105.117 1.248 1.001h1.287c-.13-1.612-1.378-2.21-2.56-2.21-1.496 0-2.432.897-2.432 1.885 0 .65.234 1.612 2.496 1.937.988.143 1.196.481 1.196.832 0 .533-.455.936-1.144.936-.689 0-1.274-.377-1.417-1.053h-1.326c.078 1.482 1.326 2.223 2.795 2.223zm6.37-.052c1.52 0 2.73-.975 2.912-2.366h-1.456c-.117.585-.598 1.144-1.43 1.144-.936 0-1.677-.819-1.677-2.21 0-1.326.74-2.106 1.65-2.106.82 0 1.314.559 1.457 1.144h1.456c-.17-1.365-1.352-2.327-2.86-2.327-1.86 0-3.172 1.404-3.172 3.38 0 1.963 1.287 3.341 3.12 3.341z" fill="#76767D"/><rect opacity=".5" x=".5" y=".5" width="35" height="23" rx=".5" stroke="#BDBEC2"/></svg>`

package/packages/search/img/search-legend-page.svg.js

@@ -0,0 +1 @@
+export default `<svg width="20" height="12" fill="none" xmlns="http://www.w3.org/2000/svg"><path stroke="#76767D" stroke-linecap="round" d="M4.5.5v11"/><path d="M1 4L4.5.5 8 4" stroke="#76767D" stroke-linecap="round" stroke-linejoin="round"/><path stroke="#76767D" stroke-linecap="round" d="M15.5.5v11"/><path d="M12 7.5l3.5 4 3.5-4" stroke="#76767D" stroke-linecap="round" stroke-linejoin="round"/></svg>`

package/packages/search/img/search-x.svg.js

@@ -0,0 +1 @@
+export default `<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1.915 1.077h13.684v13.684H1.915z"/><path d="M1.915 1.077l13.683 13.684M1.915 14.76L15.598 1.078" stroke="#76767D" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`

package/packages/search/img/search.svg.js

@@ -0,0 +1 @@
+export default `<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M8.75 15a6.25 6.25 0 100-12.5 6.25 6.25 0 000 12.5z" stroke="#76767d" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/><path d="M17.5 17.5l-4.333-4.333" stroke="#76767d" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>`

package/packages/search/img/slash-search-toggle.js

@@ -0,0 +1,17 @@
+export default function IconSlash() {
+  return (
+    <svg
+      className="icon-slash"
+      width="24"
+      height="24"
+      fill="none"
+      viewBox="0 0 24 24"
+      xmlns="http://www.w3.org/2000/svg"
+      role="img"
+    >
+      <title>{"Type '/' to Search"}</title>
+      <rect x=".5" y=".5" width="23" height="23" rx=".5" stroke="#76767D" />
+      <path d="M9 18l6-12" stroke="#76767D" strokeWidth="1.5" />
+    </svg>
+  )
+}

package/packages/search/index.js

@@ -0,0 +1,60 @@
+import { useEffect } from 'react'
+import { Configure, InstantSearch } from 'react-instantsearch-dom'
+import Hits from './hits'
+import SearchBox from './search-box'
+import SearchProvider, { useSearch } from './provider'
+
+function Search({ placeholder = 'Search', renderHitContent, resolveHitLink }) {
+  if (!renderHitContent) {
+    throw new Error(
+      'Please provide a `renderHitContent` prop to the Search component'
+    )
+  }
+
+  const {
+    client,
+    indexName,
+    initAlgoliaInsights,
+    isCancelled,
+    query,
+    setCancelled,
+    setQuery,
+  } = useSearch()
+
+  useEffect(initAlgoliaInsights, [])
+
+  function handleEscape() {
+    setCancelled(true)
+  }
+
+  return (
+    <div className="g-search">
+      <InstantSearch indexName={indexName} searchClient={client} refresh>
+        <Configure distinct={1} hitsPerPage={25} clickAnalytics />
+        <SearchBox
+          {...{
+            handleEscape,
+            placeholder,
+            query,
+            setCancelled,
+            setQuery,
+          }}
+        />
+        {query && !isCancelled && (
+          <Hits
+            {...{
+              handleEscape,
+              query,
+              renderHitContent,
+              resolveHitLink,
+              setCancelled,
+            }}
+          />
+        )}
+      </InstantSearch>
+    </div>
+  )
+}
+
+export default Search
+export { SearchProvider, useSearch }

package/packages/search/legend.js

@@ -0,0 +1,32 @@
+import InlineSvg from '@hashicorp/react-inline-svg'
+import IconEnter from './img/search-legend-enter.svg.js'
+import IconPage from './img/search-legend-page.svg.js'
+import IconEscape from './img/search-legend-escape.svg.js'
+
+export default function SearchLegend() {
+  return (
+    <div className="c-search-legend">
+      <figure className="legend-item">
+        <InlineSvg src={IconEnter} aria-hidden={true} />
+        <p className="g-type-tag-label">
+          <span className="visually-hidden">Enter</span>
+          to select
+        </p>
+      </figure>
+      <figure className="legend-item">
+        <InlineSvg src={IconPage} aria-hidden={true} />
+        <p className="g-type-tag-label">
+          <span className="visually-hidden">Tab</span>
+          to navigate
+        </p>
+      </figure>
+      <figure className="legend-item">
+        <InlineSvg src={IconEscape} aria-hidden={true} />
+        <p className="g-type-tag-label">
+          <span className="visually-hidden">Escape</span>
+          to dismiss
+        </p>
+      </figure>
+    </div>
+  )
+}