jsdoc updates

Author: gregrickaby

components/molecules/AlgoliaSearch/AlgoliaSearch.js

@@ -1,25 +1,33 @@
-import cn from 'classnames'
+import {AlgoliaContext} from '@/components/common/AlgoliaProvider'
 import parseQuerystring from '@/functions/parseQuerystring'
+import cn from 'classnames'
+import dynamic from 'next/dynamic'
 import {useRouter} from 'next/router'
 import PropTypes from 'prop-types'
 import React, {useContext, useRef, useState} from 'react'
-import {AlgoliaContext} from '@/components/common/AlgoliaProvider'
 import styles from './AlgoliaSearch.module.css'
-import dynamic from 'next/dynamic'
 import SearchPlaceholder from './components/SearchPlaceholder'
 
-/* eslint-disable */
 /**
  * This always throws an error: Component definition is missing display name.
  * Error also appears when using the NextJS example.
  *
  * @see https://nextjs.org/docs/advanced-features/dynamic-import#with-custom-loading-component
  */
 const Search = dynamic(() => import('./components/Search'), {
-  loading: () => <SearchPlaceholder />
+  loading: () => <SearchPlaceholder /> // eslint-disable-line
 })
-/* eslint-enable */
 
+/**
+ * Render the AlgoliaSearch component.
+ *
+ * @author WebDevStudios
+ * @param {object}  props                The component attributes as props.
+ * @param {string}  props.className      The component class.
+ * @param {boolean} props.useHistory     Whether to display the history.
+ * @param {boolean} props.usePlaceholder Whether to display the placeholder.
+ * @return {Element}                     The AlgoliaSearch component.
+ */
 export default function AlgoliaSearch({useHistory, usePlaceholder, className}) {
   const router = useRouter()
   const path = router?.asPath // URL from router.
@@ -29,7 +37,10 @@ export default function AlgoliaSearch({useHistory, usePlaceholder, className}) {
   const {indexName} = useContext(AlgoliaContext)
 
   /**
-   * Set a min-height value on the search wrapper to avoid DOM movement during dynamic render.
+   * Set a min-height value on the search wrapper
+   * to avoid DOM movement during dynamic render.
+   *
+   * @return {object} A minimum height value.
    */
   function setMinHeight() {
     const minHeight =
@@ -40,7 +51,8 @@ export default function AlgoliaSearch({useHistory, usePlaceholder, className}) {
   }
 
   /**
-   * Toggle the state of the Algolia `Search` and `SearchPlaceholder` components.
+   * Toggle the state of the Algolia `Search`
+   * and `SearchPlaceholder` components.
    *
    * @param {boolean} value Show/hide Algolia search input.
    */
@@ -64,9 +76,9 @@ export default function AlgoliaSearch({useHistory, usePlaceholder, className}) {
 }
 
 AlgoliaSearch.propTypes = {
+  className: PropTypes.string,
   useHistory: PropTypes.bool,
-  usePlaceholder: PropTypes.bool,
-  className: PropTypes.string
+  usePlaceholder: PropTypes.bool
 }
 
 AlgoliaSearch.defaultProps = {

components/molecules/AlgoliaSearch/components/History.js

@@ -1,25 +1,32 @@
-import PropTypes from 'prop-types'
-import styles from '../AlgoliaSearch.module.css'
 import dayjs from 'dayjs'
 import relativeTime from 'dayjs/plugin/relativeTime'
+import PropTypes from 'prop-types'
+import styles from '../AlgoliaSearch.module.css'
 
 /**
- * Component for rendering search history.
+ * Render the History component.
+ *
+ * @author WebDevStudios
+ * @param {object}   props                   The component attributes as props.
+ * @param {Function} props.buildSearchUrl    Construct Search URL and navigate user to results.
+ * @param {Function} props.clearLocalStorage Delete the localStorage for search results.
+ * @param {Array}    props.history           The history of searches.
+ * @param {Function} props.searchClick       Click Event for Search Results
+ * @return {Element}                         The History component.
  */
 export default function History({
-  history,
-  searchClick,
+  buildSearchUrl,
   clearLocalStorage,
-  buildSearchUrl
+  history,
+  searchClick
 }) {
   /**
    * Convert date and time to relative from now.
    *
-   * @author WebDevStudios
    * @see https://day.js.org/docs/en/display/from-now
    * @see https://day.js.org/docs/en/plugin/relative-time
-   * @param  {string}  time   The time as a timestamp.
-   * @return {string} newTime Returns the string of relative time from now.
+   * @param {string} time The time as a timestamp.
+   * @return {string}     Returns the string of relative time from now.
    */
   function convertDate(time) {
     dayjs.extend(relativeTime)
@@ -57,13 +64,13 @@ export default function History({
 }
 
 History.propTypes = {
+  buildSearchUrl: PropTypes.func,
+  clearLocalStorage: PropTypes.func,
   history: PropTypes.arrayOf(
     PropTypes.shape({
-      title: PropTypes.string,
-      time: PropTypes.number
+      time: PropTypes.number,
+      title: PropTypes.string
     })
   ),
-  searchClick: PropTypes.func,
-  clearLocalStorage: PropTypes.func,
-  buildSearchUrl: PropTypes.func
+  searchClick: PropTypes.func
 }

components/molecules/AlgoliaSearch/components/Hit.js

@@ -1,16 +1,22 @@
 import PropTypes from 'prop-types'
-import searchClick from '../functions/searchClick'
 import {Highlight} from 'react-instantsearch-dom'
+import searchClick from '../functions/searchClick'
 
 /**
- * Component for rendering individual search result (Hit).
+ * Render the Hit component.
+ *
+ * @author WebDevStudios
+ * @see https://www.algolia.com/doc/api-reference/widgets/hits/react/
+ * @param {object} props     The component attributes as props.
+ * @param {object} props.hit Renders each hit from the results.
+ * @return {Element}         The Hit component.
  */
 export default function Hit({hit}) {
   return (
     <button
       type="button"
       data-url={hit?.permalink}
-      data-title={hit.post_title}
+      data-title={hit?.post_title}
       onClick={(e) => searchClick(e)}
     >
       <Highlight attribute="post_title" hit={hit} />

components/molecules/AlgoliaSearch/components/Results.js

@@ -1,10 +1,10 @@
-import Hit from './Hit'
-import History from './History'
+import PropTypes from 'prop-types'
 import {connectStateResults, Hits} from 'react-instantsearch-dom'
 import styles from '../AlgoliaSearch.module.css'
-import searchClick from '../functions/searchClick'
 import buildSearchUrl from '../functions/buildSearchUrl'
-import PropTypes from 'prop-types'
+import searchClick from '../functions/searchClick'
+import History from './History'
+import Hit from './Hit'
 
 /**
  * Component for rendering Algolia `Hits` and search `History` components.

components/molecules/AlgoliaSearch/components/Search.js

@@ -1,19 +1,26 @@
 import {searchClient} from '@/api/algolia/connector'
-import searchSubmit from '../functions/searchSubmit'
 import PropTypes from 'prop-types'
 import React, {useCallback, useEffect, useState} from 'react'
 import {Configure, InstantSearch, SearchBox} from 'react-instantsearch-dom'
+import styles from '../AlgoliaSearch.module.css'
 import {deleteLocalStorage} from '../functions/localStorage'
+import searchSubmit from '../functions/searchSubmit'
 import Results from './Results'
-import styles from '../AlgoliaSearch.module.css'
 import SearchIcon from './SearchIcon'
 
 // TODO: Create Storybook for this component.
 
 /**
- * Component for rendering Algolia search with hits and history.
+ * Render the Search component.
+ *
+ * @author WebDevStudios
+ * @param {object}  props            The component attributes as props.
+ * @param {string}  props.indexName  The search index name stored in Algolia.
+ * @param {string}  props.query      The search query
+ * @param {boolean} props.useHistory Whether to display search history.
+ * @return {Element}                 The Search component.
  */
-export default function Search({indexName, useHistory, query}) {
+export default function Search({indexName, query, useHistory}) {
   const storageName = indexName // Local Storage Name - set to algolia index.
   const historyLength = 6 // Max amount of history items to save to local storage.
   const hitsPerPage = 6 // Amount of hit to render in drop results.
@@ -50,8 +57,10 @@ export default function Search({indexName, useHistory, query}) {
     }
   }, [storageName, useHistory])
 
-  // Delete recent searches and clear history.
-  const clearLocalStorage = () => {
+  /**
+   * Delete recent searches and clear history.
+   */
+  function clearLocalStorage() {
     deleteLocalStorage(storageName)
     setSearchHistory([])
   }
@@ -100,8 +109,8 @@ export default function Search({indexName, useHistory, query}) {
 
 Search.propTypes = {
   indexName: PropTypes.string.isRequired,
-  useHistory: PropTypes.bool,
-  query: PropTypes.string
+  query: PropTypes.string,
+  useHistory: PropTypes.bool
 }
 
 Search.defaultProps = {

components/molecules/AlgoliaSearch/components/SearchIcon.js

@@ -1,5 +1,8 @@
 /**
- * The magnify glass icon.
+ * Render the SearchIcon component.
+ *
+ * @author WebDevStudios
+ * @return {Element} The SearchIcon component.
  */
 export default function SearchIcon() {
   return (

components/molecules/AlgoliaSearch/components/SearchPlaceholder.js

@@ -1,10 +1,17 @@
-import SearchIcon from './SearchIcon'
-import styles from '../AlgoliaSearch.module.css'
 import PropTypes from 'prop-types'
+import styles from '../AlgoliaSearch.module.css'
+import SearchIcon from './SearchIcon'
 
 /**
- * This component renders a placeholder for the Algolia `Search` component.
- * The `Search` component is loaded using Dynamic Imports in Next once initiated by the user.
+ * Render the SearchPlaceholder component.
+ *
+ * Note: the `Search` component is loaded using Dynamic Imports.
+ *
+ * @author WebDevStudios
+ * @param {object}   props               The component attributes as props.
+ * @param {Function} props.toggleAlgolia Toggle the Search component.
+ * @param {string}   props.query         The search query.
+ * @return {Element}                     The SearchPlaceholder component.
  */
 export default function SearchPlaceholder({toggleAlgolia, query}) {
   return (

components/molecules/AlgoliaSearch/functions/buildSearchUrl.js

@@ -1,8 +1,9 @@
 /**
  * Construct Search URL and navigate user to results.
  *
- * @param  {string} Query param.
- * @return {string} destination url.
+ * @author WebDevStudios
+ * @param {string} query The search query.
+ * @return {string}      The search URL with search query.
  */
 export default function buildSearchUrl(query) {
   if (!query) {

components/molecules/AlgoliaSearch/functions/localStorage.js

@@ -5,6 +5,7 @@
  * @param {string} name      Local Storage name.
  * @param {string} value     The value to store.
  * @param {number} maxLength Maximum history items to store.
+ * @return {Function}        Sets the value of the pair identified by key to value
  */
 export function setLocalStorage(name, value, maxLength) {
   if (!localStorage) {
@@ -34,7 +35,9 @@ export function setLocalStorage(name, value, maxLength) {
 /**
  * Delete the localStorage for search results.
  *
- * @param {*} name  Local Storage name.
+ * @author WebDevStudios
+ * @param {any} name Local Storage name.
+ * @return {Function} Removes the key/value pair with the given key
  */
 export function deleteLocalStorage(name) {
   if (!name) {
@@ -46,8 +49,10 @@ export function deleteLocalStorage(name) {
 /**
  * Remove duplicate entries from local storage.
  *
- * @param {*} array
- * @param {*} value
+ * @author WebDevStudios
+ * @param {*} array Potential localStorage items.
+ * @param {*} value Potential duplicate items.
+ * @return {Array}  The the potential storage.
  */
 function removeStorageDuplicates(array = [], value = '') {
   if (!array || !value) {

components/molecules/AlgoliaSearch/functions/searchClick.js

@@ -1,10 +1,11 @@
 /**
- * Click Event for Search Results
+ * Click event for search results
  *
  * @author WebDevStudios
- * @param {*} e
+ * @param {object} e The click event.
+ * @return {object}  The routed URL.
  */
-const searchClick = (e) => {
+export default function searchClick(e) {
   const target = e.currentTarget
   if (!target) {
     return false
@@ -16,5 +17,3 @@ const searchClick = (e) => {
     window.location = url
   }
 }
-
-export default searchClick