@docusaurus/theme-search-algolia 2.0.0-beta.15d451942 → 2.0.0-beta.18

package/{src → lib}/theme/SearchPage/index.js

@@ -4,26 +4,27 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
 /* eslint-disable jsx-a11y/no-autofocus */
-
 import React, {useEffect, useState, useReducer, useRef} from 'react';
-
 import algoliaSearch from 'algoliasearch/lite';
 import algoliaSearchHelper from 'algoliasearch-helper';
 import clsx from 'clsx';
-
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
-import {useTitleFormatter, usePluralForm} from '@docusaurus/theme-common';
+import {
+  HtmlClassNameProvider,
+  useTitleFormatter,
+  usePluralForm,
+  isRegexpStringMatch,
+  useDynamicCallback,
+  useSearchPage,
+} from '@docusaurus/theme-common';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useAllDocsData} from '@theme/hooks/useDocs';
-import useSearchQuery from '@theme/hooks/useSearchQuery';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import Layout from '@theme/Layout';
 import Translate, {translate} from '@docusaurus/Translate';
 import styles from './styles.module.css';
-
 // Very simple pluralization: probably good enough for now
 function useDocumentsFoundPlural() {
   const {selectMessage} = usePluralForm();
@@ -41,26 +42,25 @@ function useDocumentsFoundPlural() {
       ),
     );
 }
-
 function useDocsSearchVersionsHelpers() {
   const allDocsData = useAllDocsData();
-
   // State of the version select menus / algolia facet filters
   // docsPluginId -> versionName map
-  const [searchVersions, setSearchVersions] = useState(() => {
-    return Object.entries(allDocsData).reduce((acc, [pluginId, pluginData]) => {
-      return {...acc, [pluginId]: pluginData.versions[0].name};
-    }, {});
-  });
-
+  const [searchVersions, setSearchVersions] = useState(() =>
+    Object.entries(allDocsData).reduce(
+      (acc, [pluginId, pluginData]) => ({
+        ...acc,
+        [pluginId]: pluginData.versions[0].name,
+      }),
+      {},
+    ),
+  );
   // Set the value of a single select menu
   const setSearchVersion = (pluginId, searchVersion) =>
     setSearchVersions((s) => ({...s, [pluginId]: searchVersion}));
-
   const versioningEnabled = Object.values(allDocsData).some(
     (docsData) => docsData.versions.length > 1,
   );
-
   return {
     allDocsData,
     versioningEnabled,
@@ -68,15 +68,13 @@ function useDocsSearchVersionsHelpers() {
     setSearchVersion,
   };
 }
-
 // We want to display one select per versioned docs plugin instance
-const SearchVersionSelectList = ({docsSearchVersionsHelpers}) => {
+function SearchVersionSelectList({docsSearchVersionsHelpers}) {
   const versionedPluginEntries = Object.entries(
     docsSearchVersionsHelpers.allDocsData,
   )
     // Do not show a version select for unversioned docs plugin instances
     .filter(([, docsData]) => docsData.versions.length > 1);
-
   return (
     <div
       className={clsx(
@@ -111,22 +109,18 @@ const SearchVersionSelectList = ({docsSearchVersionsHelpers}) => {
       })}
     </div>
   );
-};
-
-function SearchPage() {
+}
+function SearchPageContent() {
   const {
-    siteConfig: {
-      themeConfig: {
-        algolia: {appId, apiKey, indexName},
-      },
-    },
+    siteConfig: {themeConfig},
     i18n: {currentLocale},
   } = useDocusaurusContext();
+  const {
+    algolia: {appId, apiKey, indexName, externalUrlRegex},
+  } = themeConfig;
   const documentsFoundPlural = useDocumentsFoundPlural();
-
   const docsSearchVersionsHelpers = useDocsSearchVersionsHelpers();
-  const {searchValue, updateSearchPath} = useSearchQuery();
-  const [searchQuery, setSearchQuery] = useState(searchValue);
+  const {searchQuery, setSearchQuery} = useSearchPage();
   const initialSearchResultState = {
     items: [],
     query: null,
@@ -137,8 +131,8 @@ function SearchPage() {
     loading: null,
   };
   const [searchResultState, searchResultStateDispatcher] = useReducer(
-    (prevState, {type, value: state}) => {
-      switch (type) {
+    (prevState, data) => {
+      switch (data.type) {
         case 'reset': {
           return initialSearchResultState;
         }
@@ -146,21 +140,19 @@ function SearchPage() {
           return {...prevState, loading: true};
         }
         case 'update': {
-          if (searchQuery !== state.query) {
+          if (searchQuery !== data.value.query) {
             return prevState;
           }
-
           return {
-            ...state,
+            ...data.value,
             items:
-              state.lastPage === 0
-                ? state.items
-                : prevState.items.concat(state.items),
+              data.value.lastPage === 0
+                ? data.value.items
+                : prevState.items.concat(data.value.items),
           };
         }
         case 'advance': {
           const hasMore = prevState.totalPages > prevState.lastPage + 1;
-
           return {
             ...prevState,
             lastPage: hasMore ? prevState.lastPage + 1 : prevState.lastPage,
@@ -179,36 +171,33 @@ function SearchPage() {
     advancedSyntax: true,
     disjunctiveFacets: ['language', 'docusaurus_tag'],
   });
-
   algoliaHelper.on(
     'result',
     ({results: {query, hits, page, nbHits, nbPages}}) => {
-      if (query === '' || !(hits instanceof Array)) {
+      if (query === '' || !Array.isArray(hits)) {
         searchResultStateDispatcher({type: 'reset'});
         return;
       }
-
-      const sanitizeValue = (value) => {
-        return value.replace(
+      const sanitizeValue = (value) =>
+        value.replace(
           /algolia-docsearch-suggestion--highlight/g,
           'search-result-match',
         );
-      };
-
       const items = hits.map(
         ({
           url,
           _highlightResult: {hierarchy},
           _snippetResult: snippet = {},
         }) => {
-          const {pathname, hash} = new URL(url);
-          const titles = Object.keys(hierarchy).map((key) => {
-            return sanitizeValue(hierarchy[key].value);
-          });
-
+          const parsedURL = new URL(url);
+          const titles = Object.keys(hierarchy).map((key) =>
+            sanitizeValue(hierarchy[key].value),
+          );
           return {
             title: titles.pop(),
-            url: pathname + hash,
+            url: isRegexpStringMatch(externalUrlRegex, parsedURL.href)
+              ? parsedURL.href
+              : parsedURL.pathname + parsedURL.hash,
             summary: snippet.content
               ? `${sanitizeValue(snippet.content.value)}...`
               : '',
@@ -216,7 +205,6 @@ function SearchPage() {
           };
         },
       );
-
       searchResultStateDispatcher({
         type: 'update',
         value: {
@@ -231,7 +219,6 @@ function SearchPage() {
       });
     },
   );
-
   const [loaderRef, setLoaderRef] = useState(null);
   const prevY = useRef(0);
   const observer = useRef(
@@ -242,17 +229,14 @@ function SearchPage() {
             isIntersecting,
             boundingClientRect: {y: currentY},
           } = entries[0];
-
           if (isIntersecting && prevY.current > currentY) {
             searchResultStateDispatcher({type: 'advance'});
           }
-
           prevY.current = currentY;
         },
         {threshold: 1},
       ),
   );
-
   const getTitle = () =>
     searchQuery
       ? translate(
@@ -270,11 +254,9 @@ function SearchPage() {
           message: 'Search the documentation',
           description: 'The search page title for empty query',
         });
-
-  const makeSearch = (page = 0) => {
+  const makeSearch = useDynamicCallback((page = 0) => {
     algoliaHelper.addDisjunctiveFacetRefinement('docusaurus_tag', 'default');
     algoliaHelper.addDisjunctiveFacetRefinement('language', currentLocale);
-
     Object.entries(docsSearchVersionsHelpers.searchVersions).forEach(
       ([pluginId, searchVersion]) => {
         algoliaHelper.addDisjunctiveFacetRefinement(
@@ -283,52 +265,36 @@ function SearchPage() {
         );
       },
     );
-
     algoliaHelper.setQuery(searchQuery).setPage(page).search();
-  };
-
+  });
   useEffect(() => {
     if (!loaderRef) {
       return undefined;
     }
-
-    observer.current.observe(loaderRef);
-
-    return () => {
-      observer.current.unobserve(loaderRef);
-    };
+    const currentObserver = observer.current;
+    if (currentObserver) {
+      currentObserver.observe(loaderRef);
+      return () => currentObserver.unobserve(loaderRef);
+    }
+    return () => true;
   }, [loaderRef]);
-
   useEffect(() => {
-    updateSearchPath(searchQuery);
-
     searchResultStateDispatcher({type: 'reset'});
-
     if (searchQuery) {
       searchResultStateDispatcher({type: 'loading'});
-
       setTimeout(() => {
         makeSearch();
       }, 300);
     }
-  }, [searchQuery, docsSearchVersionsHelpers.searchVersions]);
-
+  }, [searchQuery, docsSearchVersionsHelpers.searchVersions, makeSearch]);
   useEffect(() => {
     if (!searchResultState.lastPage || searchResultState.lastPage === 0) {
       return;
     }
-
     makeSearch(searchResultState.lastPage);
-  }, [searchResultState.lastPage]);
-
-  useEffect(() => {
-    if (searchValue && searchValue !== searchQuery) {
-      setSearchQuery(searchValue);
-    }
-  }, [searchValue]);
-
+  }, [makeSearch, searchResultState.lastPage]);
   return (
-    <Layout wrapperClassName="search-page-wrapper">
+    <Layout>
       <Head>
         <title>{useTitleFormatter(getTitle())}</title>
         {/*
@@ -375,16 +341,19 @@ function SearchPage() {
           )}
         </form>
 
-        <div className={clsx('row', 'margin-vert--sm')}>
+        <div className="row">
           <div className={clsx('col', 'col--8', styles.searchResultsColumn)}>
-            {!!searchResultState.totalResults && (
-              <strong>
-                {documentsFoundPlural(searchResultState.totalResults)}
-              </strong>
-            )}
+            {!!searchResultState.totalResults &&
+              documentsFoundPlural(searchResultState.totalResults)}
           </div>
 
-          <div className={clsx('col', 'col--4', styles.searchLogoColumn)}>
+          <div
+            className={clsx(
+              'col',
+              'col--4',
+              'text--right',
+              styles.searchLogoColumn,
+            )}>
             <a
               target="_blank"
               rel="noopener noreferrer"
@@ -394,10 +363,7 @@ function SearchPage() {
                 message: 'Search by Algolia',
                 description: 'The ARIA label for Algolia mention',
               })}>
-              <svg
-                viewBox="0 0 168 24"
-                className={styles.algoliaLogo}
-                xmlns="http://www.w3.org/2000/svg">
+              <svg viewBox="0 0 168 24" className={styles.algoliaLogo}>
                 <g fill="none">
                   <path
                     className={styles.algoliaLogoPathFill}
@@ -418,34 +384,32 @@ function SearchPage() {
         </div>
 
         {searchResultState.items.length > 0 ? (
-          <section>
+          <main>
             {searchResultState.items.map(
               ({title, url, summary, breadcrumbs}, i) => (
                 <article key={i} className={styles.searchResultItem}>
-                  <Link
-                    to={url}
-                    className={styles.searchResultItemHeading}
-                    dangerouslySetInnerHTML={{__html: title}}
-                  />
+                  <h2 className={styles.searchResultItemHeading}>
+                    <Link to={url} dangerouslySetInnerHTML={{__html: title}} />
+                  </h2>
 
                   {breadcrumbs.length > 0 && (
-                    <span className={styles.searchResultItemPath}>
-                      {breadcrumbs.map((html, index) => (
-                        <React.Fragment key={index}>
-                          {index !== 0 && (
-                            <span
-                              className={styles.searchResultItemPathSeparator}>
-                              ›
-                            </span>
-                          )}
-                          <span
+                    <nav aria-label="breadcrumbs">
+                      <ul
+                        className={clsx(
+                          'breadcrumbs',
+                          styles.searchResultItemPath,
+                        )}>
+                        {breadcrumbs.map((html, index) => (
+                          <li
+                            key={index}
+                            className="breadcrumbs__item"
                             // Developer provided the HTML, so assume it's safe.
                             // eslint-disable-next-line react/no-danger
                             dangerouslySetInnerHTML={{__html: html}}
                           />
-                        </React.Fragment>
-                      ))}
-                    </span>
+                        ))}
+                      </ul>
+                    </nav>
                   )}
 
                   {summary && (
@@ -459,7 +423,7 @@ function SearchPage() {
                 </article>
               ),
             )}
-          </section>
+          </main>
         ) : (
           [
             searchQuery && !searchResultState.loading && (
@@ -479,18 +443,21 @@ function SearchPage() {
 
         {searchResultState.hasMore && (
           <div className={styles.loader} ref={setLoaderRef}>
-            <span>
-              <Translate
-                id="theme.SearchPage.fetchingNewResults"
-                description="The paragraph for fetching new search results">
-                Fetching new results...
-              </Translate>
-            </span>
+            <Translate
+              id="theme.SearchPage.fetchingNewResults"
+              description="The paragraph for fetching new search results">
+              Fetching new results...
+            </Translate>
           </div>
         )}
       </div>
     </Layout>
   );
 }
-
-export default SearchPage;
+export default function SearchPage() {
+  return (
+    <HtmlClassNameProvider className="search-page-wrapper">
+      <SearchPageContent />
+    </HtmlClassNameProvider>
+  );
+}

package/lib/theme/SearchPage/styles.module.css

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.searchQueryInput,
+.searchVersionInput {
+  border-radius: var(--ifm-global-radius);
+  border: 2px solid var(--ifm-toc-border-color);
+  font: var(--ifm-font-size-base) var(--ifm-font-family-base);
+  padding: 0.8rem;
+  width: 100%;
+  background: var(--docsearch-searchbox-focus-background);
+  color: var(--docsearch-text-color);
+  margin-bottom: 0.5rem;
+  transition: border var(--ifm-transition-fast) ease;
+}
+
+.searchQueryInput:focus,
+.searchVersionInput:focus {
+  border-color: var(--docsearch-primary-color);
+  outline: none;
+}
+
+.searchQueryInput::placeholder {
+  color: var(--docsearch-muted-color);
+}
+
+.searchResultsColumn {
+  font-size: 0.9rem;
+  font-weight: bold;
+}
+
+.algoliaLogo {
+  max-width: 150px;
+}
+
+.algoliaLogoPathFill {
+  fill: var(--ifm-font-color-base);
+}
+
+.searchResultItem {
+  padding: 1rem 0;
+  border-bottom: 1px solid var(--ifm-toc-border-color);
+}
+
+.searchResultItemHeading {
+  font-weight: 400;
+  margin-bottom: 0;
+}
+
+.searchResultItemPath {
+  font-size: 0.8rem;
+  color: var(--ifm-color-content-secondary);
+  --ifm-breadcrumb-separator-size-multiplier: 1;
+}
+
+.searchResultItemSummary {
+  margin: 0.5rem 0 0;
+  font-style: italic;
+}
+
+@media only screen and (max-width: 996px) {
+  .searchQueryColumn {
+    max-width: 60% !important;
+  }
+
+  .searchVersionColumn {
+    max-width: 40% !important;
+  }
+
+  .searchResultsColumn {
+    max-width: 60% !important;
+  }
+
+  .searchLogoColumn {
+    max-width: 40% !important;
+    padding-left: 0 !important;
+  }
+}
+
+@media screen and (max-width: 576px) {
+  .searchQueryColumn {
+    max-width: 100% !important;
+  }
+
+  .searchVersionColumn {
+    max-width: 100% !important;
+    padding-left: var(--ifm-spacing-horizontal) !important;
+  }
+}
+
+.loadingSpinner {
+  width: 3rem;
+  height: 3rem;
+  border: 0.4em solid #eee;
+  border-top-color: var(--ifm-color-primary);
+  border-radius: 50%;
+  animation: loading-spin 1s linear infinite;
+  margin: 0 auto;
+}
+
+@keyframes loading-spin {
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+.loader {
+  margin-top: 2rem;
+}
+
+:global(.search-result-match) {
+  color: var(--docsearch-hit-color);
+  background: rgb(255 215 142 / 25%);
+  padding: 0.09em 0;
+}

package/lib/validateThemeConfig.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Joi } from '@docusaurus/utils-validation';
+import type { ThemeConfig, ThemeConfigValidationContext } from '@docusaurus/types';
+export declare const DEFAULT_CONFIG: {
+    contextualSearch: boolean;
+    searchParameters: {};
+    searchPagePath: string;
+};
+export declare const Schema: Joi.ObjectSchema<any>;
+export declare function validateThemeConfig({ validate, themeConfig, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;

package/lib/validateThemeConfig.js

@@ -0,0 +1,50 @@
+'use strict';
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, '__esModule', {value: true});
+exports.validateThemeConfig = exports.Schema = exports.DEFAULT_CONFIG = void 0;
+const utils_validation_1 = require('@docusaurus/utils-validation');
+exports.DEFAULT_CONFIG = {
+  // enabled by default, as it makes sense in most cases
+  // see also https://github.com/facebook/docusaurus/issues/5880
+  contextualSearch: true,
+  searchParameters: {},
+  searchPagePath: 'search',
+};
+exports.Schema = utils_validation_1.Joi.object({
+  algolia: utils_validation_1.Joi.object({
+    // Docusaurus attributes
+    contextualSearch: utils_validation_1.Joi.boolean().default(
+      exports.DEFAULT_CONFIG.contextualSearch,
+    ),
+    externalUrlRegex: utils_validation_1.Joi.string().optional(),
+    // Algolia attributes
+    appId: utils_validation_1.Joi.string().required().messages({
+      'any.required':
+        '"algolia.appId" is required. If you haven\'t migrated to the new DocSearch infra, please refer to the blog post for instructions: https://docusaurus.io/blog/2021/11/21/algolia-docsearch-migration',
+    }),
+    apiKey: utils_validation_1.Joi.string().required(),
+    indexName: utils_validation_1.Joi.string().required(),
+    searchParameters: utils_validation_1.Joi.object()
+      .default(exports.DEFAULT_CONFIG.searchParameters)
+      .unknown(),
+    searchPagePath: utils_validation_1.Joi.alternatives()
+      .try(
+        utils_validation_1.Joi.boolean().invalid(true),
+        utils_validation_1.Joi.string(),
+      )
+      .allow(null)
+      .default(exports.DEFAULT_CONFIG.searchPagePath),
+  })
+    .label('themeConfig.algolia')
+    .required()
+    .unknown(), // DocSearch 3 is still alpha: don't validate the rest for now
+});
+function validateThemeConfig({validate, themeConfig}) {
+  return validate(exports.Schema, themeConfig);
+}
+exports.validateThemeConfig = validateThemeConfig;

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@docusaurus/theme-search-algolia",
-  "version": "2.0.0-beta.15d451942",
+  "version": "2.0.0-beta.18",
   "description": "Algolia search component for Docusaurus.",
-  "main": "src/index.js",
+  "main": "lib/index.js",
+  "exports": {
+    "./client": "./lib/client/index.js",
+    ".": "./lib/index.js"
+  },
+  "types": "src/theme-search-algolia.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -12,24 +17,40 @@
     "directory": "packages/docusaurus-theme-search-algolia"
   },
   "license": "MIT",
+  "scripts": {
+    "build": "yarn build:server && yarn build:client && yarn build:copy && yarn build:format",
+    "build:server": "tsc --project tsconfig.server.json",
+    "build:client": "tsc --project tsconfig.client.json",
+    "build:copy": "node copyUntypedFiles.mjs",
+    "build:format": "prettier --config ../../.prettierrc --write \"lib/**/*.js\""
+  },
   "dependencies": {
-    "@docsearch/react": "^3.0.0-alpha.36",
-    "@docusaurus/core": "2.0.0-beta.15d451942",
-    "@docusaurus/theme-common": "2.0.0-beta.15d451942",
-    "@docusaurus/utils": "2.0.0-beta.15d451942",
-    "@docusaurus/utils-validation": "2.0.0-beta.15d451942",
-    "algoliasearch": "^4.8.4",
-    "algoliasearch-helper": "^3.3.4",
+    "@docsearch/react": "^3.0.0",
+    "@docusaurus/core": "2.0.0-beta.18",
+    "@docusaurus/logger": "2.0.0-beta.18",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.18",
+    "@docusaurus/theme-common": "2.0.0-beta.18",
+    "@docusaurus/theme-translations": "2.0.0-beta.18",
+    "@docusaurus/utils": "2.0.0-beta.18",
+    "@docusaurus/utils-validation": "2.0.0-beta.18",
+    "algoliasearch": "^4.13.0",
+    "algoliasearch-helper": "^3.7.4",
     "clsx": "^1.1.1",
-    "eta": "^1.12.1",
-    "lodash": "^4.17.20"
+    "eta": "^1.12.3",
+    "fs-extra": "^10.0.1",
+    "lodash": "^4.17.21",
+    "tslib": "^2.3.1",
+    "utility-types": "^3.10.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.18"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "dfceae8bd3e8b42ba8fc14f1449d861046c26143"
+  "gitHead": "1a945d06993d53376e61bed2c942799fe07dc336"
 }