fix(search): search page should react to querystring changes + cleanup/refactor (#8757)

packages/docusaurus-theme-common/src/hooks/useSearchPage.ts

@@ -5,32 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useCallback, useEffect, useState} from 'react';
+import {useCallback} from 'react';
-import {useHistory} from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useQueryString} from '../utils/historyUtils';
 import type {ThemeConfig as AlgoliaThemeConfig} from '@docusaurus/theme-search-algolia';
 
 const SEARCH_PARAM_QUERY = 'q';
 
-/** Some utility functions around search queries. */
+/**
-export function useSearchPage(): {
+ * Permits to read/write the current search query string
-  /**
+ */
-   * Works hand-in-hand with `setSearchQuery`; whatever the user has inputted
+export function useSearchQueryString(): [string, (newValue: string) => void] {
-   * into the search box.
+  return useQueryString(SEARCH_PARAM_QUERY);
-   */
+}
-  searchQuery: string;
+
-  /**
+/**
-   * Set a new search query. In addition to updating `searchQuery`, this handle
+ * Permits to create links to the search page with the appropriate query string
-   * also mutates the location and appends the query.
+ */
-   */
+export function useSearchLinkCreator(): (searchValue: string) => string {
-  setSearchQuery: (newSearchQuery: string) => void;
-  /**
-   * Given a query, this handle generates the corresponding search page link,
-   * with base URL prepended.
-   */
-  generateSearchPageLink: (targetSearchQuery: string) => string;
-} {
-  const history = useHistory();
   const {
     siteConfig: {baseUrl, themeConfig},
   } = useDocusaurusContext();
@@ -38,47 +30,13 @@ export function useSearchPage(): {
     algolia: {searchPagePath},
   } = themeConfig as AlgoliaThemeConfig;
 
-  const [searchQuery, setSearchQueryState] = useState('');
+  return useCallback(
-
+    (searchValue: string) =>
-  // 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
       // Note: if searchPagePath is falsy, useSearchPage() will not be called
       `${baseUrl}${
         searchPagePath as string
-      }?${SEARCH_PARAM_QUERY}=${encodeURIComponent(targetSearchQuery)}`,
+      }?${SEARCH_PARAM_QUERY}=${encodeURIComponent(searchValue)}`,
     [baseUrl, searchPagePath],
   );
-
-  return {
-    searchQuery,
-    setSearchQuery,
-    generateSearchPageLink,
-  };
 }

packages/docusaurus-theme-common/src/index.ts

@@ -73,6 +73,11 @@ export {
   type TagLetterEntry,
 } from './utils/tagsUtils';
 
+export {
+  useSearchQueryString,
+  useSearchLinkCreator,
+} from './hooks/useSearchPage';
+
 export {isMultiColumnFooterLinks} from './utils/footerUtils';
 
 export {isRegexpStringMatch} from './utils/regexpUtils';

packages/docusaurus-theme-common/src/internal.ts

@@ -121,7 +121,6 @@ export {
   keyboardFocusedClassName,
 } from './hooks/useKeyboardNavigation';
 export {useLockBodyScroll} from './hooks/useLockBodyScroll';
-export {useSearchPage} from './hooks/useSearchPage';
 export {useCodeWordWrap} from './hooks/useCodeWordWrap';
 export {getPrismCssVariables} from './utils/codeBlockUtils';
 export {useBackToTopButton} from './hooks/useBackToTopButton';

packages/docusaurus-theme-common/src/utils/historyUtils.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useEffect} from 'react';
+import {useCallback, useEffect} from 'react';
 import {useHistory} from '@docusaurus/router';
 // @ts-expect-error: TODO temporary until React 18 upgrade
 import {useSyncExternalStore} from 'use-sync-external-store/shim';
@@ -75,3 +75,42 @@ export function useQueryStringValue(key: string | null): string | null {
     return new URLSearchParams(history.location.search).get(key);
   });
 }
+
+export function useQueryStringKeySetter(): (
+  key: string,
+  newValue: string | null,
+  options?: {push: boolean},
+) => void {
+  const history = useHistory();
+  return useCallback(
+    (key, newValue, options) => {
+      const searchParams = new URLSearchParams(history.location.search);
+      if (newValue) {
+        searchParams.set(key, newValue);
+      } else {
+        searchParams.delete(key);
+      }
+      const updaterFn = options?.push ? history.push : history.replace;
+      updaterFn({
+        search: searchParams.toString(),
+      });
+    },
+    [history],
+  );
+}
+
+export function useQueryString(
+  key: string,
+): [string, (newValue: string, options?: {push: boolean}) => void] {
+  const value = useQueryStringValue(key) ?? '';
+  const setQueryString = useQueryStringKeySetter();
+  return [
+    value,
+    useCallback(
+      (newValue: string, options) => {
+        setQueryString(key, newValue, options);
+      },
+      [setQueryString, key],
+    ),
+  ];
+}

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx

@@ -10,8 +10,10 @@ import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
 import {useHistory} from '@docusaurus/router';
-import {isRegexpStringMatch} from '@docusaurus/theme-common';
+import {
-import {useSearchPage} from '@docusaurus/theme-common/internal';
+  isRegexpStringMatch,
+  useSearchLinkCreator,
+} from '@docusaurus/theme-common';
 import {
   useAlgoliaContextualFacetFilters,
   useSearchResultUrlProcessor,
@@ -59,10 +61,10 @@ type ResultsFooterProps = {
 };
 
 function ResultsFooter({state, onClose}: ResultsFooterProps) {
-  const {generateSearchPageLink} = useSearchPage();
+  const createSearchLink = useSearchLinkCreator();
 
   return (
-    <Link to={generateSearchPageLink(state.query)} onClick={onClose}>
+    <Link to={createSearchLink(state.query)} onClick={onClose}>
       <Translate
         id="theme.SearchBar.seeAll"
         values={{count: state.context.nbHits}}>

packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx

@@ -21,11 +21,9 @@ import {
   HtmlClassNameProvider,
   useEvent,
   usePluralForm,
+  useSearchQueryString,
 } from '@docusaurus/theme-common';
-import {
+import {useTitleFormatter} from '@docusaurus/theme-common/internal';
-  useSearchPage,
-  useTitleFormatter,
-} from '@docusaurus/theme-common/internal';
 import Translate, {translate} from '@docusaurus/Translate';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {
@@ -167,7 +165,7 @@ function SearchPageContent(): JSX.Element {
   const documentsFoundPlural = useDocumentsFoundPlural();
 
   const docsSearchVersionsHelpers = useDocsSearchVersionsHelpers();
-  const {searchQuery, setSearchQuery} = useSearchPage();
+  const [searchQuery, setSearchQuery] = useSearchQueryString();
   const initialSearchResultState: ResultDispatcherState = {
     items: [],
     query: null,