docs: render api ref urls in search (#27594)

docs/src/theme/SearchBar/index.js

@@ -0,0 +1,202 @@
+import React, {useCallback, useMemo, useRef, useState} from 'react';
+import {createPortal} from 'react-dom';
+import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
+import Head from '@docusaurus/Head';
+import Link from '@docusaurus/Link';
+import {useHistory} from '@docusaurus/router';
+import {
+  isRegexpStringMatch,
+  useSearchLinkCreator,
+} from '@docusaurus/theme-common';
+import {
+  useAlgoliaContextualFacetFilters,
+  useSearchResultUrlProcessor,
+} from '@docusaurus/theme-search-algolia/client';
+import Translate from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import translations from '@theme/SearchTranslations';
+let DocSearchModal = null;
+function Hit({hit, children}) {
+  if (hit.url.includes('/api_reference/')) {
+    return (
+      <a href={
+        hit.url
+      }>
+        {children}
+      </a>
+    )
+  }
+  return <Link to={hit.url}>{children}</Link>;
+}
+function ResultsFooter({state, onClose}) {
+  const createSearchLink = useSearchLinkCreator();
+  return (
+    <Link to={createSearchLink(state.query)} onClick={onClose}>
+      <Translate
+        id="theme.SearchBar.seeAll"
+        values={{count: state.context.nbHits}}>
+        {'See all {count} results'}
+      </Translate>
+    </Link>
+  );
+}
+function mergeFacetFilters(f1, f2) {
+  const normalize = (f) => (typeof f === 'string' ? [f] : f);
+  return [...normalize(f1), ...normalize(f2)];
+}
+function DocSearch({contextualSearch, externalUrlRegex, ...props}) {
+  const {siteMetadata} = useDocusaurusContext();
+  const processSearchResultUrl = useSearchResultUrlProcessor();
+  const contextualSearchFacetFilters = useAlgoliaContextualFacetFilters();
+  const configFacetFilters = props.searchParameters?.facetFilters ?? [];
+  const facetFilters = contextualSearch
+    ? // Merge contextual search filters with config filters
+      mergeFacetFilters(contextualSearchFacetFilters, configFacetFilters)
+    : // ... or use config facetFilters
+      configFacetFilters;
+  // We let user override default searchParameters if she wants to
+  const searchParameters = {
+    ...props.searchParameters,
+    facetFilters,
+  };
+  const history = useHistory();
+  const searchContainer = useRef(null);
+  const searchButtonRef = useRef(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [initialQuery, setInitialQuery] = useState(undefined);
+  const importDocSearchModalIfNeeded = useCallback(() => {
+    if (DocSearchModal) {
+      return Promise.resolve();
+    }
+    return Promise.all([
+      import('@docsearch/react/modal'),
+      import('@docsearch/react/style'),
+      import('./styles.css'),
+    ]).then(([{DocSearchModal: Modal}]) => {
+      DocSearchModal = Modal;
+    });
+  }, []);
+  const prepareSearchContainer = useCallback(() => {
+    if (!searchContainer.current) {
+      const divElement = document.createElement('div');
+      searchContainer.current = divElement;
+      document.body.insertBefore(divElement, document.body.firstChild);
+    }
+  }, []);
+  const openModal = useCallback(() => {
+    prepareSearchContainer();
+    importDocSearchModalIfNeeded().then(() => setIsOpen(true));
+  }, [importDocSearchModalIfNeeded, prepareSearchContainer]);
+  const closeModal = useCallback(() => {
+    setIsOpen(false);
+    searchButtonRef.current?.focus();
+  }, []);
+  const handleInput = useCallback(
+    (event) => {
+      if (event.key === 'f' && (event.metaKey || event.ctrlKey)) {
+        // ignore browser's ctrl+f
+        return;
+      }
+      // prevents duplicate key insertion in the modal input
+      event.preventDefault();
+      setInitialQuery(event.key);
+      openModal();
+    },
+    [openModal],
+  );
+  const navigator = useRef({
+    navigate({itemUrl}) {
+      // 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) || itemUrl.includes('/api_reference/')) {
+        window.location.href = itemUrl;
+      } else {
+        history.push(itemUrl);
+      }
+    },
+  }).current;
+  const transformItems = useRef((items) =>
+    props.transformItems
+      ? // Custom transformItems
+        props.transformItems(items)
+      : // Default transformItems
+        items.map((item) => ({
+          ...item,
+          url: processSearchResultUrl(item.url),
+        })),
+  ).current;
+  const resultsFooterComponent = useMemo(
+    () =>
+      // eslint-disable-next-line react/no-unstable-nested-components
+      (footerProps) =>
+        <ResultsFooter {...footerProps} onClose={closeModal} />,
+    [closeModal],
+  );
+  const transformSearchClient = useCallback(
+    (searchClient) => {
+      searchClient.addAlgoliaAgent(
+        'docusaurus',
+        siteMetadata.docusaurusVersion,
+      );
+      return searchClient;
+    },
+    [siteMetadata.docusaurusVersion],
+  );
+  useDocSearchKeyboardEvents({
+    isOpen,
+    onOpen: openModal,
+    onClose: closeModal,
+    onInput: handleInput,
+    searchButtonRef,
+  });
+  return (
+    <>
+      <Head>
+        {/* This hints the browser that the website will load data from Algolia,
+        and allows it to preconnect to the DocSearch cluster. It makes the first
+        query faster, especially on mobile. */}
+        <link
+          rel="preconnect"
+          href={`https://${props.appId}-dsn.algolia.net`}
+          crossOrigin="anonymous"
+        />
+      </Head>
+
+      <DocSearchButton
+        onTouchStart={importDocSearchModalIfNeeded}
+        onFocus={importDocSearchModalIfNeeded}
+        onMouseOver={importDocSearchModalIfNeeded}
+        onClick={openModal}
+        ref={searchButtonRef}
+        translations={translations.button}
+      />
+
+      {isOpen &&
+        DocSearchModal &&
+        searchContainer.current &&
+        createPortal(
+          <DocSearchModal
+            onClose={closeModal}
+            initialScrollY={window.scrollY}
+            initialQuery={initialQuery}
+            navigator={navigator}
+            transformItems={transformItems}
+            hitComponent={Hit}
+            transformSearchClient={transformSearchClient}
+            {...(props.searchPagePath && {
+              resultsFooterComponent,
+            })}
+            {...props}
+            searchParameters={searchParameters}
+            placeholder={translations.placeholder}
+            translations={translations.modal}
+          />,
+          searchContainer.current,
+        )}
+    </>
+  );
+}
+export default function SearchBar() {
+  const {siteConfig} = useDocusaurusContext();
+  return <DocSearch {...siteConfig.themeConfig.algolia} />;
+}

docs/src/theme/SearchBar/styles.css

@@ -0,0 +1,14 @@
+:root {
+  --docsearch-primary-color: var(--ifm-color-primary);
+  --docsearch-text-color: var(--ifm-font-color-base);
+}
+
+.DocSearch-Button {
+  margin: 0;
+  transition: all var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
+}
+
+.DocSearch-Container {
+  z-index: calc(var(--ifm-z-index-fixed) + 1);
+}

docs/src/theme/SearchPage/styles.module.css

@@ -0,0 +1,112 @@
+.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;
+}