@docusaurus/theme-search-algolia 2.0.0-beta.1 → 2.0.0-beta.10

package/src/{index.js → index.ts}

@@ -5,29 +5,38 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const path = require('path');
-const fs = require('fs');
-const eta = require('eta');
-const {normalizeUrl, getSwizzledComponent} = require('@docusaurus/utils');
-const openSearchTemplate = require('./templates/opensearch');
-const {validateThemeConfig} = require('./validateThemeConfig');
-const {memoize} = require('lodash');
+import path from 'path';
+import fs from 'fs';
+import {defaultConfig, compile} from 'eta';
+import {normalizeUrl, getSwizzledComponent} from '@docusaurus/utils';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import openSearchTemplate from './templates/opensearch';
+import {memoize} from 'lodash';
 
-const getCompiledOpenSearchTemplate = memoize(() => {
-  return eta.compile(openSearchTemplate.trim());
-});
+import type {DocusaurusContext, Plugin} from '@docusaurus/types';
 
-function renderOpenSearchTemplate(data) {
+const getCompiledOpenSearchTemplate = memoize(() =>
+  compile(openSearchTemplate.trim()),
+);
+
+function renderOpenSearchTemplate(data: {
+  title: string;
+  url: string;
+  favicon: string | null;
+}) {
   const compiled = getCompiledOpenSearchTemplate();
-  return compiled(data, eta.defaultConfig);
+  return compiled(data, defaultConfig);
 }
 
 const OPEN_SEARCH_FILENAME = 'opensearch.xml';
 
-function theme(context) {
+export default function theme(
+  context: DocusaurusContext & {baseUrl: string},
+): Plugin<void> {
   const {
     baseUrl,
     siteConfig: {title, url, favicon},
+    i18n: {currentLocale},
   } = context;
   const pageComponent = './theme/SearchPage/index.js';
   const pagePath =
@@ -37,12 +46,23 @@ function theme(context) {
   return {
     name: 'docusaurus-theme-search-algolia',
 
+    getPathsToWatch() {
+      return [pagePath];
+    },
+
     getThemePath() {
       return path.resolve(__dirname, './theme');
     },
 
-    getPathsToWatch() {
-      return [pagePath];
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, '..', 'src', 'theme');
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'theme-search-algolia',
+      });
     },
 
     async contentLoaded({actions: {addRoute}}) {
@@ -60,7 +80,7 @@ function theme(context) {
           renderOpenSearchTemplate({
             title,
             url: url + baseUrl,
-            favicon: normalizeUrl([url, baseUrl, favicon]),
+            favicon: favicon ? normalizeUrl([url, baseUrl, favicon]) : null,
           }),
         );
       } catch (err) {
@@ -87,6 +107,4 @@ function theme(context) {
   };
 }
 
-module.exports = theme;
-
-theme.validateThemeConfig = validateThemeConfig;
+export {validateThemeConfig} from './validateThemeConfig';

package/src/templates/{opensearch.js → opensearch.ts}

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-module.exports = `
+export default `
 <?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                        xmlns:moz="http://www.mozilla.org/2006/browser/search/">
   <ShortName><%= it.title %></ShortName>
   <Description>Search <%= it.title %></Description>
   <InputEncoding>UTF-8</InputEncoding>
-  <Image width="16" height="16" type="image/x-icon"><%= it.favicon %></Image>
+  <% if (it.favicon) { _%>
+    <Image width="16" height="16" type="image/x-icon"><%= it.favicon %></Image>
+  <% } _%>
   <Url type="text/html" method="get" template="<%= it.url %>search?q={searchTerms}"/>
   <Url type="application/opensearchdescription+xml" rel="self" template="<%= it.url %>opensearch.xml" />
   <moz:SearchForm><%= it.url %></moz:SearchForm>

package/src/theme/SearchBar/{index.js → index.tsx}

@@ -4,6 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/* eslint-disable @typescript-eslint/ban-ts-comment */
 
 import React, {useState, useRef, useCallback, useMemo} from 'react';
 import {createPortal} from 'react-dom';
@@ -13,18 +14,48 @@ import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import Link from '@docusaurus/Link';
 import Head from '@docusaurus/Head';
 import useSearchQuery from '@theme/hooks/useSearchQuery';
+import {isRegexpStringMatch} from '@docusaurus/theme-common';
 import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
 import useAlgoliaContextualFacetFilters from '@theme/hooks/useAlgoliaContextualFacetFilters';
 import {translate} from '@docusaurus/Translate';
 import styles from './styles.module.css';
 
-let DocSearchModal = null;
+import type {
+  DocSearchModal as DocSearchModalType,
+  DocSearchModalProps,
+} from '@docsearch/react';
+import type {
+  InternalDocSearchHit,
+  StoredDocSearchHit,
+} from '@docsearch/react/dist/esm/types';
+import type {AutocompleteState} from '@algolia/autocomplete-core';
 
-function Hit({hit, children}) {
+type DocSearchProps = Omit<
+  DocSearchModalProps,
+  'onClose' | 'initialScrollY'
+> & {
+  contextualSearch?: string;
+  externalUrlRegex?: string;
+};
+
+let DocSearchModal: typeof DocSearchModalType | null = null;
+
+function Hit({
+  hit,
+  children,
+}: {
+  hit: InternalDocSearchHit | StoredDocSearchHit;
+  children: React.ReactNode;
+}) {
   return <Link to={hit.url}>{children}</Link>;
 }
 
-function ResultsFooter({state, onClose}) {
+type ResultsFooterProps = {
+  state: AutocompleteState<InternalDocSearchHit>;
+  onClose: () => void;
+};
+
+function ResultsFooter({state, onClose}: ResultsFooterProps) {
   const {generateSearchPageLink} = useSearchQuery();
 
   return (
@@ -34,7 +65,11 @@ function ResultsFooter({state, onClose}) {
   );
 }
 
-function DocSearch({contextualSearch, ...props}) {
+function DocSearch({
+  contextualSearch,
+  externalUrlRegex,
+  ...props
+}: DocSearchProps) {
   const {siteMetadata} = useDocusaurusContext();
 
   const contextualSearchFacetFilters = useAlgoliaContextualFacetFilters();
@@ -55,10 +90,12 @@ function DocSearch({contextualSearch, ...props}) {
 
   const {withBaseUrl} = useBaseUrlUtils();
   const history = useHistory();
-  const searchContainer = useRef(null);
-  const searchButtonRef = useRef(null);
+  const searchContainer = useRef<HTMLDivElement | null>(null);
+  const searchButtonRef = useRef<HTMLButtonElement>(null);
   const [isOpen, setIsOpen] = useState(false);
-  const [initialQuery, setInitialQuery] = useState(null);
+  const [initialQuery, setInitialQuery] = useState<string | undefined>(
+    undefined,
+  );
 
   const importDocSearchModalIfNeeded = useCallback(() => {
     if (DocSearchModal) {
@@ -66,7 +103,9 @@ function DocSearch({contextualSearch, ...props}) {
     }
 
     return Promise.all([
+      // @ts-ignore
       import('@docsearch/react/modal'),
+      // @ts-ignore
       import('@docsearch/react/style'),
       import('./styles.css'),
     ]).then(([{DocSearchModal: Modal}]) => {
@@ -87,7 +126,7 @@ function DocSearch({contextualSearch, ...props}) {
 
   const onClose = useCallback(() => {
     setIsOpen(false);
-    searchContainer.current.remove();
+    searchContainer.current?.remove();
   }, [setIsOpen]);
 
   const onInput = useCallback(
@@ -101,28 +140,38 @@ function DocSearch({contextualSearch, ...props}) {
   );
 
   const navigator = useRef({
-    navigate({itemUrl}) {
-      history.push(itemUrl);
+    navigate({itemUrl}: {itemUrl?: string}) {
+      // Algolia results could contain URL's from other domains which cannot
+      // be served through history and should navigate with window.location
+      if (isRegexpStringMatch(externalUrlRegex, itemUrl)) {
+        window.location.href = itemUrl!;
+      } else {
+        history.push(itemUrl!);
+      }
     },
   }).current;
 
-  const transformItems = useRef((items) => {
-    return items.map((item) => {
-      // We transform the absolute URL into a relative URL.
-      // Alternatively, we can use `new URL(item.url)` but it's not
-      // supported in IE.
-      const a = document.createElement('a');
-      a.href = item.url;
-
-      return {
-        ...item,
-        url: withBaseUrl(`${a.pathname}${a.hash}`),
-      };
-    });
-  }).current;
+  const transformItems = useRef<DocSearchModalProps['transformItems']>(
+    (items) =>
+      items.map((item) => {
+        // If Algolia contains a external domain, we should navigate without relative URL
+        if (isRegexpStringMatch(externalUrlRegex, item.url)) {
+          return item;
+        }
+
+        // We transform the absolute URL into a relative URL.
+        const url = new URL(item.url);
+        return {
+          ...item,
+          url: withBaseUrl(`${url.pathname}${url.hash}`),
+        };
+      }),
+  ).current;
 
   const resultsFooterComponent = useMemo(
-    () => (footerProps) => <ResultsFooter {...footerProps} onClose={onClose} />,
+    // eslint-disable-next-line react/no-unstable-nested-components
+    () => (footerProps: ResultsFooterProps) =>
+      <ResultsFooter {...footerProps} onClose={onClose} />,
     [onClose],
   );
 
@@ -180,6 +229,8 @@ function DocSearch({contextualSearch, ...props}) {
       </div>
 
       {isOpen &&
+        DocSearchModal &&
+        searchContainer.current &&
         createPortal(
           <DocSearchModal
             onClose={onClose}
@@ -199,8 +250,9 @@ function DocSearch({contextualSearch, ...props}) {
   );
 }
 
-function SearchBar() {
+function SearchBar(): JSX.Element {
   const {siteConfig} = useDocusaurusContext();
+  // @ts-ignore
   return <DocSearch {...siteConfig.themeConfig.algolia} />;
 }
 

package/src/theme/{SearchMetadatas/index.js → SearchMetadata/index.tsx}

@@ -8,9 +8,14 @@
 import React from 'react';
 
 import Head from '@docusaurus/Head';
+import type {SearchMetadataProps} from '@theme/SearchMetadata';
 
-// Override default/agnostic SearchMetas to use Algolia-specific metadatas
-export default function AlgoliaSearchMetadatas({locale, version, tag}) {
+// Override default/agnostic SearchMetas to use Algolia-specific metadata
+function SearchMetadata({
+  locale,
+  version,
+  tag,
+}: SearchMetadataProps): JSX.Element {
   // Seems safe to consider here the locale is the language,
   // as the existing docsearch:language filter is afaik a regular string-based filter
   const language = locale;
@@ -23,3 +28,5 @@ export default function AlgoliaSearchMetadatas({locale, version, tag}) {
     </Head>
   );
 }
+
+export default SearchMetadata;

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

@@ -6,6 +6,7 @@
  */
 
 /* eslint-disable jsx-a11y/no-autofocus */
+/* eslint-disable @typescript-eslint/ban-ts-comment */
 
 import React, {useEffect, useState, useReducer, useRef} from 'react';
 
@@ -16,7 +17,12 @@ 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 {
+  useTitleFormatter,
+  usePluralForm,
+  isRegexpStringMatch,
+  useDynamicCallback,
+} from '@docusaurus/theme-common';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useAllDocsData} from '@theme/hooks/useDocs';
 import useSearchQuery from '@theme/hooks/useSearchQuery';
@@ -27,7 +33,7 @@ import styles from './styles.module.css';
 // Very simple pluralization: probably good enough for now
 function useDocumentsFoundPlural() {
   const {selectMessage} = usePluralForm();
-  return (count) =>
+  return (count: number) =>
     selectMessage(
       count,
       translate(
@@ -47,14 +53,19 @@ function useDocsSearchVersionsHelpers() {
 
   // 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<Record<string, string>>(
+    () =>
+      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) =>
+  const setSearchVersion = (pluginId: string, searchVersion: string) =>
     setSearchVersions((s) => ({...s, [pluginId]: searchVersion}));
 
   const versioningEnabled = Object.values(allDocsData).some(
@@ -70,7 +81,11 @@ function useDocsSearchVersionsHelpers() {
 }
 
 // We want to display one select per versioned docs plugin instance
-const SearchVersionSelectList = ({docsSearchVersionsHelpers}) => {
+function SearchVersionSelectList({
+  docsSearchVersionsHelpers,
+}: {
+  docsSearchVersionsHelpers: ReturnType<typeof useDocsSearchVersionsHelpers>;
+}) {
   const versionedPluginEntries = Object.entries(
     docsSearchVersionsHelpers.allDocsData,
   )
@@ -111,13 +126,35 @@ const SearchVersionSelectList = ({docsSearchVersionsHelpers}) => {
       })}
     </div>
   );
+}
+
+type ResultDispatcherState = {
+  items: {
+    title: string;
+    url: string;
+    summary: string;
+    breadcrumbs: string[];
+  }[];
+  query: string | null;
+  totalResults: number | null;
+  totalPages: number | null;
+  lastPage: number | null;
+  hasMore: boolean | null;
+  loading: boolean | null;
 };
 
-function SearchPage() {
+type ResultDispatcher =
+  | {type: 'reset'; value?: undefined}
+  | {type: 'loading'; value?: undefined}
+  | {type: 'update'; value: ResultDispatcherState}
+  | {type: 'advance'; value?: undefined};
+
+function SearchPage(): JSX.Element {
   const {
     siteConfig: {
       themeConfig: {
-        algolia: {appId, apiKey, indexName},
+        // @ts-ignore
+        algolia: {appId, apiKey, indexName, externalUrlRegex},
       },
     },
     i18n: {currentLocale},
@@ -125,9 +162,8 @@ function SearchPage() {
   const documentsFoundPlural = useDocumentsFoundPlural();
 
   const docsSearchVersionsHelpers = useDocsSearchVersionsHelpers();
-  const {searchValue, updateSearchPath} = useSearchQuery();
-  const [searchQuery, setSearchQuery] = useState(searchValue);
-  const initialSearchResultState = {
+  const {searchQuery, setSearchQuery} = useSearchQuery();
+  const initialSearchResultState: ResultDispatcherState = {
     items: [],
     query: null,
     totalResults: null,
@@ -137,8 +173,8 @@ function SearchPage() {
     loading: null,
   };
   const [searchResultState, searchResultStateDispatcher] = useReducer(
-    (prevState, {type, value: state}) => {
-      switch (type) {
+    (prevState: ResultDispatcherState, data: ResultDispatcher) => {
+      switch (data.type) {
         case 'reset': {
           return initialSearchResultState;
         }
@@ -146,24 +182,24 @@ 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;
+          const hasMore = prevState.totalPages! > prevState.lastPage! + 1;
 
           return {
             ...prevState,
-            lastPage: hasMore ? prevState.lastPage + 1 : prevState.lastPage,
+            lastPage: hasMore ? prevState.lastPage! + 1 : prevState.lastPage,
             hasMore,
           };
         }
@@ -173,6 +209,7 @@ function SearchPage() {
     },
     initialSearchResultState,
   );
+
   const algoliaClient = algoliaSearch(appId, apiKey);
   const algoliaHelper = algoliaSearchHelper(algoliaClient, indexName, {
     hitsPerPage: 15,
@@ -188,12 +225,11 @@ function SearchPage() {
         return;
       }
 
-      const sanitizeValue = (value) => {
-        return value.replace(
+      const sanitizeValue = (value: string) =>
+        value.replace(
           /algolia-docsearch-suggestion--highlight/g,
           'search-result-match',
         );
-      };
 
       const items = hits.map(
         ({
@@ -201,14 +237,16 @@ function SearchPage() {
           _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,
+            title: titles.pop()!,
+            url: isRegexpStringMatch(externalUrlRegex, parsedURL.href)
+              ? parsedURL.href
+              : parsedURL.pathname + parsedURL.hash,
             summary: snippet.content
               ? `${sanitizeValue(snippet.content.value)}...`
               : '',
@@ -232,7 +270,7 @@ function SearchPage() {
     },
   );
 
-  const [loaderRef, setLoaderRef] = useState(null);
+  const [loaderRef, setLoaderRef] = useState<HTMLDivElement | null>(null);
   const prevY = useRef(0);
   const observer = useRef(
     ExecutionEnvironment.canUseDOM &&
@@ -271,7 +309,7 @@ function SearchPage() {
           description: 'The search page title for empty query',
         });
 
-  const makeSearch = (page = 0) => {
+  const makeSearch = useDynamicCallback((page: number = 0) => {
     algoliaHelper.addDisjunctiveFacetRefinement('docusaurus_tag', 'default');
     algoliaHelper.addDisjunctiveFacetRefinement('language', currentLocale);
 
@@ -285,23 +323,21 @@ 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) {
@@ -311,7 +347,7 @@ function SearchPage() {
         makeSearch();
       }, 300);
     }
-  }, [searchQuery, docsSearchVersionsHelpers.searchVersions]);
+  }, [searchQuery, docsSearchVersionsHelpers.searchVersions, makeSearch]);
 
   useEffect(() => {
     if (!searchResultState.lastPage || searchResultState.lastPage === 0) {
@@ -319,13 +355,7 @@ function SearchPage() {
     }
 
     makeSearch(searchResultState.lastPage);
-  }, [searchResultState.lastPage]);
-
-  useEffect(() => {
-    if (searchValue && searchValue !== searchQuery) {
-      setSearchQuery(searchValue);
-    }
-  }, [searchValue]);
+  }, [makeSearch, searchResultState.lastPage]);
 
   return (
     <Layout wrapperClassName="search-page-wrapper">

package/src/theme/hooks/{useAlgoliaContextualFacetFilters.js → useAlgoliaContextualFacetFilters.ts}

@@ -5,13 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import useContextualSearchFilters from '@theme/hooks/useContextualSearchFilters';
+import type {useAlgoliaContextualFacetFiltersReturns} from '@theme/hooks/useAlgoliaContextualFacetFilters';
+import {useContextualSearchFilters} from '@docusaurus/theme-common';
 
 // Translate search-engine agnostic search filters to Algolia search filters
-export default function useAlgoliaContextualFacetFilters() {
+export default function useAlgoliaContextualFacetFilters(): useAlgoliaContextualFacetFiltersReturns {
   const {locale, tags} = useContextualSearchFilters();
 
-  // seems safe to convert locale->language, see AlgoliaSearchMetadatas comment
+  // seems safe to convert locale->language, see AlgoliaSearchMetadata comment
   const languageFilter = `language:${locale}`;
 
   const tagsFilter = tags.map((tag) => `docusaurus_tag:${tag}`);

package/src/theme/hooks/useSearchQuery.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 {useHistory} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useCallback, useEffect, useState} from 'react';
+import type {SearchQuery} from '@theme/hooks/useSearchQuery';
+
+const SEARCH_PARAM_QUERY = 'q';
+
+function useSearchQuery(): SearchQuery {
+  const history = useHistory();
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+
+  const [searchQuery, setSearchQueryState] = useState('');
+
+  // Init search query just after React hydration
+  useEffect(() => {
+    const searchQueryStringValue =
+      new URLSearchParams(window.location.search).get(SEARCH_PARAM_QUERY) ?? '';
+
+    setSearchQueryState(searchQueryStringValue);
+  }, []);
+
+  const setSearchQuery = useCallback(
+    (newSearchQuery: string) => {
+      const searchParams = new URLSearchParams(window.location.search);
+
+      if (newSearchQuery) {
+        searchParams.set(SEARCH_PARAM_QUERY, newSearchQuery);
+      } else {
+        searchParams.delete(SEARCH_PARAM_QUERY);
+      }
+
+      history.replace({
+        search: searchParams.toString(),
+      });
+      setSearchQueryState(newSearchQuery);
+    },
+    [history],
+  );
+
+  const generateSearchPageLink = useCallback(
+    (targetSearchQuery: string) =>
+      // Refer to https://github.com/facebook/docusaurus/pull/2838
+      `${baseUrl}search?q=${encodeURIComponent(targetSearchQuery)}`,
+    [baseUrl],
+  );
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    generateSearchPageLink,
+  };
+}
+
+export default useSearchQuery;