@docusaurus/theme-search-algolia 2.0.0-beta.fc64c12e4 → 2.0.0

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

@@ -4,26 +4,29 @@
  * 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 clsx from 'clsx';
 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,
+  usePluralForm,
+  isRegexpStringMatch,
+  useEvent,
+} from '@docusaurus/theme-common';
+import {
+  useTitleFormatter,
+  useSearchPage,
+} from '@docusaurus/theme-common/internal';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useAllDocsData} from '@theme/hooks/useDocs';
-import useSearchQuery from '@theme/hooks/useSearchQuery';
-import Layout from '@theme/Layout';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import Translate, {translate} from '@docusaurus/Translate';
+import Layout from '@theme/Layout';
 import styles from './styles.module.css';
-
 // Very simple pluralization: probably good enough for now
 function useDocumentsFoundPlural() {
   const {selectMessage} = usePluralForm();
@@ -41,26 +44,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 +70,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 +111,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 +133,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 +142,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 +173,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 +207,6 @@ function SearchPage() {
           };
         },
       );
-
       searchResultStateDispatcher({
         type: 'update',
         value: {
@@ -231,28 +221,24 @@ function SearchPage() {
       });
     },
   );
-
   const [loaderRef, setLoaderRef] = useState(null);
   const prevY = useRef(0);
   const observer = useRef(
-    ExecutionEnvironment.canUseDOM &&
+    ExecutionEnvironment.canUseIntersectionObserver &&
       new IntersectionObserver(
         (entries) => {
           const {
             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 +256,9 @@ function SearchPage() {
           message: 'Search the documentation',
           description: 'The search page title for empty query',
         });
-
-  const makeSearch = (page = 0) => {
+  const makeSearch = useEvent((page = 0) => {
     algoliaHelper.addDisjunctiveFacetRefinement('docusaurus_tag', 'default');
     algoliaHelper.addDisjunctiveFacetRefinement('language', currentLocale);
-
     Object.entries(docsSearchVersionsHelpers.searchVersions).forEach(
       ([pluginId, searchVersion]) => {
         algoliaHelper.addDisjunctiveFacetRefinement(
@@ -283,52 +267,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>
         {/*
@@ -488,5 +456,10 @@ function SearchPage() {
     </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/theme/SearchTranslations/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 type { DocSearchTranslations } from '@docsearch/react';
+declare const translations: DocSearchTranslations & {
+    placeholder: string;
+};
+export default translations;

package/lib/theme/SearchTranslations/index.js

@@ -0,0 +1,167 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+const translations = {
+  button: {
+    buttonText: translate({
+      id: 'theme.SearchBar.label',
+      message: 'Search',
+      description: 'The ARIA label and placeholder for search button',
+    }),
+    buttonAriaLabel: translate({
+      id: 'theme.SearchBar.label',
+      message: 'Search',
+      description: 'The ARIA label and placeholder for search button',
+    }),
+  },
+  modal: {
+    searchBox: {
+      resetButtonTitle: translate({
+        id: 'theme.SearchModal.searchBox.resetButtonTitle',
+        message: 'Clear the query',
+        description: 'The label and ARIA label for search box reset button',
+      }),
+      resetButtonAriaLabel: translate({
+        id: 'theme.SearchModal.searchBox.resetButtonTitle',
+        message: 'Clear the query',
+        description: 'The label and ARIA label for search box reset button',
+      }),
+      cancelButtonText: translate({
+        id: 'theme.SearchModal.searchBox.cancelButtonText',
+        message: 'Cancel',
+        description: 'The label and ARIA label for search box cancel button',
+      }),
+      cancelButtonAriaLabel: translate({
+        id: 'theme.SearchModal.searchBox.cancelButtonText',
+        message: 'Cancel',
+        description: 'The label and ARIA label for search box cancel button',
+      }),
+    },
+    startScreen: {
+      recentSearchesTitle: translate({
+        id: 'theme.SearchModal.startScreen.recentSearchesTitle',
+        message: 'Recent',
+        description: 'The title for recent searches',
+      }),
+      noRecentSearchesText: translate({
+        id: 'theme.SearchModal.startScreen.noRecentSearchesText',
+        message: 'No recent searches',
+        description: 'The text when no recent searches',
+      }),
+      saveRecentSearchButtonTitle: translate({
+        id: 'theme.SearchModal.startScreen.saveRecentSearchButtonTitle',
+        message: 'Save this search',
+        description: 'The label for save recent search button',
+      }),
+      removeRecentSearchButtonTitle: translate({
+        id: 'theme.SearchModal.startScreen.removeRecentSearchButtonTitle',
+        message: 'Remove this search from history',
+        description: 'The label for remove recent search button',
+      }),
+      favoriteSearchesTitle: translate({
+        id: 'theme.SearchModal.startScreen.favoriteSearchesTitle',
+        message: 'Favorite',
+        description: 'The title for favorite searches',
+      }),
+      removeFavoriteSearchButtonTitle: translate({
+        id: 'theme.SearchModal.startScreen.removeFavoriteSearchButtonTitle',
+        message: 'Remove this search from favorites',
+        description: 'The label for remove favorite search button',
+      }),
+    },
+    errorScreen: {
+      titleText: translate({
+        id: 'theme.SearchModal.errorScreen.titleText',
+        message: 'Unable to fetch results',
+        description: 'The title for error screen of search modal',
+      }),
+      helpText: translate({
+        id: 'theme.SearchModal.errorScreen.helpText',
+        message: 'You might want to check your network connection.',
+        description: 'The help text for error screen of search modal',
+      }),
+    },
+    footer: {
+      selectText: translate({
+        id: 'theme.SearchModal.footer.selectText',
+        message: 'to select',
+        description: 'The explanatory text of the action for the enter key',
+      }),
+      selectKeyAriaLabel: translate({
+        id: 'theme.SearchModal.footer.selectKeyAriaLabel',
+        message: 'Enter key',
+        description:
+          'The ARIA label for the Enter key button that makes the selection',
+      }),
+      navigateText: translate({
+        id: 'theme.SearchModal.footer.navigateText',
+        message: 'to navigate',
+        description:
+          'The explanatory text of the action for the Arrow up and Arrow down key',
+      }),
+      navigateUpKeyAriaLabel: translate({
+        id: 'theme.SearchModal.footer.navigateUpKeyAriaLabel',
+        message: 'Arrow up',
+        description:
+          'The ARIA label for the Arrow up key button that makes the navigation',
+      }),
+      navigateDownKeyAriaLabel: translate({
+        id: 'theme.SearchModal.footer.navigateDownKeyAriaLabel',
+        message: 'Arrow down',
+        description:
+          'The ARIA label for the Arrow down key button that makes the navigation',
+      }),
+      closeText: translate({
+        id: 'theme.SearchModal.footer.closeText',
+        message: 'to close',
+        description: 'The explanatory text of the action for Escape key',
+      }),
+      closeKeyAriaLabel: translate({
+        id: 'theme.SearchModal.footer.closeKeyAriaLabel',
+        message: 'Escape key',
+        description:
+          'The ARIA label for the Escape key button that close the modal',
+      }),
+      searchByText: translate({
+        id: 'theme.SearchModal.footer.searchByText',
+        message: 'Search by',
+        description: 'The text explain that the search is making by Algolia',
+      }),
+    },
+    noResultsScreen: {
+      noResultsText: translate({
+        id: 'theme.SearchModal.noResultsScreen.noResultsText',
+        message: 'No results for',
+        description:
+          'The text explains that there are no results for the following search',
+      }),
+      suggestedQueryText: translate({
+        id: 'theme.SearchModal.noResultsScreen.suggestedQueryText',
+        message: 'Try searching for',
+        description:
+          'The text for the suggested query when no results are found for the following search',
+      }),
+      reportMissingResultsText: translate({
+        id: 'theme.SearchModal.noResultsScreen.reportMissingResultsText',
+        message: 'Believe this query should return results?',
+        description:
+          'The text for the question where the user thinks there are missing results',
+      }),
+      reportMissingResultsLinkText: translate({
+        id: 'theme.SearchModal.noResultsScreen.reportMissingResultsLinkText',
+        message: 'Let us know.',
+        description: 'The text for the link to report missing results',
+      }),
+    },
+  },
+  placeholder: translate({
+    id: 'theme.SearchModal.placeholder',
+    message: 'Search docs',
+    description: 'The placeholder of the input of the DocSearch pop-up modal',
+  }),
+};
+export default translations;

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<ThemeConfig>;
+export declare function validateThemeConfig({ validate, themeConfig, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;

package/lib/validateThemeConfig.js

@@ -0,0 +1,44 @@
+"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;