@docusaurus/theme-search-algolia 2.0.0-beta.2 → 2.0.0-beta.22

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "@docusaurus/theme-search-algolia",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.22",
   "description": "Algolia search component for Docusaurus.",
-  "main": "src/index.js",
+  "main": "lib/index.js",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    ".": {
+      "types": "./src/theme-search-algolia.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "types": "src/theme-search-algolia.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -12,24 +26,39 @@
     "directory": "packages/docusaurus-theme-search-algolia"
   },
   "license": "MIT",
+  "scripts": {
+    "build": "tsc --build && node ../../admin/scripts/copyUntypedFiles.js && prettier --config ../../.prettierrc --write \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
+  },
   "dependencies": {
-    "@docsearch/react": "^3.0.0-alpha.36",
-    "@docusaurus/core": "2.0.0-beta.2",
-    "@docusaurus/theme-common": "2.0.0-beta.2",
-    "@docusaurus/utils": "2.0.0-beta.2",
-    "@docusaurus/utils-validation": "2.0.0-beta.2",
-    "algoliasearch": "^4.8.4",
-    "algoliasearch-helper": "^3.3.4",
-    "clsx": "^1.1.1",
-    "eta": "^1.12.1",
-    "lodash": "^4.17.20"
+    "@docsearch/react": "^3.1.1",
+    "@docusaurus/core": "2.0.0-beta.22",
+    "@docusaurus/logger": "2.0.0-beta.22",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.22",
+    "@docusaurus/theme-common": "2.0.0-beta.22",
+    "@docusaurus/theme-translations": "2.0.0-beta.22",
+    "@docusaurus/utils": "2.0.0-beta.22",
+    "@docusaurus/utils-validation": "2.0.0-beta.22",
+    "algoliasearch": "^4.13.1",
+    "algoliasearch-helper": "^3.10.0",
+    "clsx": "^1.2.0",
+    "eta": "^1.12.3",
+    "fs-extra": "^10.1.0",
+    "lodash": "^4.17.21",
+    "tslib": "^2.4.0",
+    "utility-types": "^3.10.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.22"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=16.14"
   },
-  "gitHead": "883f07fddffaf1657407c8e202e370cc436e25f7"
+  "gitHead": "daf9e462c4eebb7ac26a940932311f987e768f87"
 }

package/src/client/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export {useAlgoliaContextualFacetFilters} from './useAlgoliaContextualFacetFilters';

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

@@ -5,13 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import useContextualSearchFilters from '@theme/hooks/useContextualSearchFilters';
+import {useContextualSearchFilters} from '@docusaurus/theme-common';
 
 // Translate search-engine agnostic search filters to Algolia search filters
-export default function useAlgoliaContextualFacetFilters() {
+export function useAlgoliaContextualFacetFilters(): [string, string[]] {
   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/deps.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+
+declare module '@docsearch/react/modal';
+
+declare module '@docsearch/react/style';
+
+// TODO incompatible declaration file
+declare module 'eta' {
+  export const defaultConfig: object;
+
+  export function compile(
+    template: string,
+    options?: object,
+  ): (data: object, config: object) => string;
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 path from 'path';
+import fs from 'fs-extra';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {defaultConfig, compile} from 'eta';
+import {normalizeUrl} from '@docusaurus/utils';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import openSearchTemplate from './templates/opensearch';
+
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
+
+const getCompiledOpenSearchTemplate = _.memoize(() =>
+  compile(openSearchTemplate.trim()),
+);
+
+function renderOpenSearchTemplate(data: {
+  title: string;
+  siteUrl: string;
+  searchUrl: string;
+  faviconUrl: string | null;
+}) {
+  const compiled = getCompiledOpenSearchTemplate();
+  return compiled(data, defaultConfig);
+}
+
+const OPEN_SEARCH_FILENAME = 'opensearch.xml';
+
+export default function themeSearchAlgolia(context: LoadContext): Plugin<void> {
+  const {
+    baseUrl,
+    siteConfig: {title, url, favicon, themeConfig},
+    i18n: {currentLocale},
+  } = context;
+  const {
+    algolia: {searchPagePath},
+  } = themeConfig as ThemeConfig;
+
+  return {
+    name: 'docusaurus-theme-search-algolia',
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'theme-search-algolia',
+      });
+    },
+
+    contentLoaded({actions: {addRoute}}) {
+      if (searchPagePath) {
+        addRoute({
+          path: normalizeUrl([baseUrl, searchPagePath]),
+          component: '@theme/SearchPage',
+          exact: true,
+        });
+      }
+    },
+
+    async postBuild({outDir}) {
+      if (searchPagePath) {
+        const siteUrl = normalizeUrl([url, baseUrl]);
+
+        try {
+          await fs.writeFile(
+            path.join(outDir, OPEN_SEARCH_FILENAME),
+            renderOpenSearchTemplate({
+              title,
+              siteUrl,
+              searchUrl: normalizeUrl([siteUrl, searchPagePath]),
+              faviconUrl: favicon ? normalizeUrl([siteUrl, favicon]) : null,
+            }),
+          );
+        } catch (err) {
+          logger.error('Generating OpenSearch file failed.');
+          throw err;
+        }
+      }
+    },
+
+    injectHtmlTags() {
+      if (!searchPagePath) {
+        return {};
+      }
+
+      return {
+        headTags: [
+          {
+            tagName: 'link',
+            attributes: {
+              rel: 'search',
+              type: 'application/opensearchdescription+xml',
+              title,
+              href: normalizeUrl([baseUrl, OPEN_SEARCH_FILENAME]),
+            },
+          },
+        ],
+      };
+    },
+  };
+}
+
+export {validateThemeConfig} from './validateThemeConfig';

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

@@ -5,16 +5,18 @@
  * 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>
-  <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>
+  <% if (it.faviconUrl) { _%>
+    <Image width="16" height="16" type="image/x-icon"><%= it.faviconUrl %></Image>
+  <% } _%>
+  <Url type="text/html" method="get" template="<%= it.searchUrl %>?q={searchTerms}"/>
+  <Url type="application/opensearchdescription+xml" rel="self" template="<%= it.siteUrl %>opensearch.xml" />
+  <moz:SearchForm><%= it.siteUrl %></moz:SearchForm>
 </OpenSearchDescription>
 `;

package/src/theme/SearchBar/index.tsx

@@ -0,0 +1,271 @@
+/**
+ * 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 React, {useState, useRef, useCallback, useMemo} from 'react';
+import {createPortal} from 'react-dom';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useHistory} from '@docusaurus/router';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import Link from '@docusaurus/Link';
+import Head from '@docusaurus/Head';
+import {isRegexpStringMatch} from '@docusaurus/theme-common';
+import {useSearchPage} from '@docusaurus/theme-common/internal';
+import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
+import {useAlgoliaContextualFacetFilters} from '@docusaurus/theme-search-algolia/client';
+import Translate from '@docusaurus/Translate';
+import translations from '@theme/SearchTranslations';
+
+import type {
+  DocSearchModal as DocSearchModalType,
+  DocSearchModalProps,
+} from '@docsearch/react';
+import type {
+  InternalDocSearchHit,
+  StoredDocSearchHit,
+} from '@docsearch/react/dist/esm/types';
+import type {SearchClient} from 'algoliasearch/lite';
+import type {AutocompleteState} from '@algolia/autocomplete-core';
+
+type DocSearchProps = Omit<
+  DocSearchModalProps,
+  'onClose' | 'initialScrollY'
+> & {
+  contextualSearch?: string;
+  externalUrlRegex?: string;
+  searchPagePath: boolean | string;
+};
+
+let DocSearchModal: typeof DocSearchModalType | null = null;
+
+function Hit({
+  hit,
+  children,
+}: {
+  hit: InternalDocSearchHit | StoredDocSearchHit;
+  children: React.ReactNode;
+}) {
+  return <Link to={hit.url}>{children}</Link>;
+}
+
+type ResultsFooterProps = {
+  state: AutocompleteState<InternalDocSearchHit>;
+  onClose: () => void;
+};
+
+function ResultsFooter({state, onClose}: ResultsFooterProps) {
+  const {generateSearchPageLink} = useSearchPage();
+
+  return (
+    <Link to={generateSearchPageLink(state.query)} onClick={onClose}>
+      <Translate
+        id="theme.SearchBar.seeAll"
+        values={{count: state.context.nbHits}}>
+        {'See all {count} results'}
+      </Translate>
+    </Link>
+  );
+}
+
+type FacetFilters = Required<
+  Required<DocSearchProps>['searchParameters']
+>['facetFilters'];
+
+function mergeFacetFilters(f1: FacetFilters, f2: FacetFilters): FacetFilters {
+  const normalize = (
+    f: FacetFilters,
+  ): readonly string[] | readonly (string | readonly string[])[] =>
+    typeof f === 'string' ? [f] : f;
+  return [...normalize(f1), ...normalize(f2)] as FacetFilters;
+}
+
+function DocSearch({
+  contextualSearch,
+  externalUrlRegex,
+  ...props
+}: DocSearchProps) {
+  const {siteMetadata} = useDocusaurusContext();
+
+  const contextualSearchFacetFilters =
+    useAlgoliaContextualFacetFilters() as FacetFilters;
+
+  const configFacetFilters: FacetFilters =
+    props.searchParameters?.facetFilters ?? [];
+
+  const facetFilters: 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: DocSearchProps['searchParameters'] = {
+    ...props.searchParameters,
+    facetFilters,
+  };
+
+  const {withBaseUrl} = useBaseUrlUtils();
+  const history = useHistory();
+  const searchContainer = useRef<HTMLDivElement | null>(null);
+  const searchButtonRef = useRef<HTMLButtonElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const [initialQuery, setInitialQuery] = useState<string | undefined>(
+    undefined,
+  );
+
+  const importDocSearchModalIfNeeded = useCallback(() => {
+    if (DocSearchModal) {
+      return Promise.resolve();
+    }
+
+    return Promise.all([
+      import('@docsearch/react/modal') as Promise<
+        typeof import('@docsearch/react')
+      >,
+      import('@docsearch/react/style'),
+      import('./styles.css'),
+    ]).then(([{DocSearchModal: Modal}]) => {
+      DocSearchModal = Modal;
+    });
+  }, []);
+
+  const onOpen = useCallback(() => {
+    importDocSearchModalIfNeeded().then(() => {
+      searchContainer.current = document.createElement('div');
+      document.body.insertBefore(
+        searchContainer.current,
+        document.body.firstChild,
+      );
+      setIsOpen(true);
+    });
+  }, [importDocSearchModalIfNeeded, setIsOpen]);
+
+  const onClose = useCallback(() => {
+    setIsOpen(false);
+    searchContainer.current?.remove();
+  }, [setIsOpen]);
+
+  const onInput = useCallback(
+    (event: KeyboardEvent) => {
+      importDocSearchModalIfNeeded().then(() => {
+        setIsOpen(true);
+        setInitialQuery(event.key);
+      });
+    },
+    [importDocSearchModalIfNeeded, setIsOpen, setInitialQuery],
+  );
+
+  const navigator = useRef({
+    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<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: DocSearchProps['resultsFooterComponent'] =
+    useMemo(
+      () =>
+        // eslint-disable-next-line react/no-unstable-nested-components
+        (footerProps: Omit<ResultsFooterProps, 'onClose'>): JSX.Element =>
+          <ResultsFooter {...footerProps} onClose={onClose} />,
+      [onClose],
+    );
+
+  const transformSearchClient = useCallback(
+    (searchClient: SearchClient) => {
+      searchClient.addAlgoliaAgent(
+        'docusaurus',
+        siteMetadata.docusaurusVersion,
+      );
+
+      return searchClient;
+    },
+    [siteMetadata.docusaurusVersion],
+  );
+
+  useDocSearchKeyboardEvents({
+    isOpen,
+    onOpen,
+    onClose,
+    onInput,
+    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={onOpen}
+        ref={searchButtonRef}
+        translations={translations.button}
+      />
+
+      {isOpen &&
+        DocSearchModal &&
+        searchContainer.current &&
+        createPortal(
+          <DocSearchModal
+            onClose={onClose}
+            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(): JSX.Element {
+  const {siteConfig} = useDocusaurusContext();
+  return <DocSearch {...(siteConfig.themeConfig.algolia as DocSearchProps)} />;
+}