@docusaurus/theme-search-algolia 0.0.0-5416 → 0.0.0-5426

package/lib/client/index.d.ts

@@ -4,4 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+export { useAlgoliaThemeConfig } from './useAlgoliaThemeConfig';
 export { useAlgoliaContextualFacetFilters } from './useAlgoliaContextualFacetFilters';
+export { useSearchResultUrlProcessor } from './useSearchResultUrlProcessor';

package/lib/client/index.js

@@ -4,4 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+export { useAlgoliaThemeConfig } from './useAlgoliaThemeConfig';
 export { useAlgoliaContextualFacetFilters } from './useAlgoliaContextualFacetFilters';
+export { useSearchResultUrlProcessor } from './useSearchResultUrlProcessor';

package/lib/client/useAlgoliaThemeConfig.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeConfig } from '@docusaurus/theme-search-algolia';
+export declare function useAlgoliaThemeConfig(): ThemeConfig;

package/lib/client/useAlgoliaThemeConfig.js

@@ -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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+export function useAlgoliaThemeConfig() {
+    const { siteConfig: { themeConfig }, } = useDocusaurusContext();
+    return themeConfig;
+}

package/lib/client/useSearchResultUrlProcessor.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.
+ */
+/**
+ * Process the search result url from Algolia to its final form, ready to be
+ * navigated to or used as a link
+ */
+export declare function useSearchResultUrlProcessor(): (url: string) => string;

package/lib/client/useSearchResultUrlProcessor.js

@@ -0,0 +1,33 @@
+/**
+ * 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 { useCallback } from 'react';
+import { isRegexpStringMatch } from '@docusaurus/theme-common';
+import { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
+import { useAlgoliaThemeConfig } from './useAlgoliaThemeConfig';
+function replacePathname(pathname, replaceSearchResultPathname) {
+    return replaceSearchResultPathname
+        ? pathname.replaceAll(new RegExp(replaceSearchResultPathname.from, 'g'), replaceSearchResultPathname.to)
+        : pathname;
+}
+/**
+ * Process the search result url from Algolia to its final form, ready to be
+ * navigated to or used as a link
+ */
+export function useSearchResultUrlProcessor() {
+    const { withBaseUrl } = useBaseUrlUtils();
+    const { algolia: { externalUrlRegex, replaceSearchResultPathname }, } = useAlgoliaThemeConfig();
+    return useCallback((url) => {
+        const parsedURL = new URL(url);
+        // Algolia contains an external domain => navigate to URL
+        if (isRegexpStringMatch(externalUrlRegex, parsedURL.href)) {
+            return url;
+        }
+        // Otherwise => transform to relative URL for SPA navigation
+        const relativeUrl = `${parsedURL.pathname + parsedURL.hash}`;
+        return withBaseUrl(replacePathname(relativeUrl, replaceSearchResultPathname));
+    }, [withBaseUrl, externalUrlRegex, replaceSearchResultPathname]);
+}

package/lib/theme/SearchBar/index.js

@@ -4,18 +4,20 @@
  * 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 React, {useCallback, useMemo, useRef, useState} from 'react';
+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 {useSearchPage} from '@docusaurus/theme-common/internal';
-import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
-import {useAlgoliaContextualFacetFilters} from '@docusaurus/theme-search-algolia/client';
+import {
+  useAlgoliaContextualFacetFilters,
+  useSearchResultUrlProcessor,
+} from '@docusaurus/theme-search-algolia/client';
 import Translate from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {createPortal} from 'react-dom';
 import translations from '@theme/SearchTranslations';
 let DocSearchModal = null;
 function Hit({hit, children}) {
@@ -39,6 +41,7 @@ function mergeFacetFilters(f1, f2) {
 }
 function DocSearch({contextualSearch, externalUrlRegex, ...props}) {
   const {siteMetadata} = useDocusaurusContext();
+  const processSearchResultUrl = useSearchResultUrlProcessor();
   const contextualSearchFacetFilters = useAlgoliaContextualFacetFilters();
   const configFacetFilters = props.searchParameters?.facetFilters ?? [];
   const facetFilters = contextualSearch
@@ -51,7 +54,6 @@ function DocSearch({contextualSearch, externalUrlRegex, ...props}) {
     ...props.searchParameters,
     facetFilters,
   };
-  const {withBaseUrl} = useBaseUrlUtils();
   const history = useHistory();
   const searchContainer = useRef(null);
   const searchButtonRef = useRef(null);
@@ -104,19 +106,10 @@ function DocSearch({contextualSearch, externalUrlRegex, ...props}) {
     },
   }).current;
   const transformItems = useRef((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}`),
-      };
-    }),
+    items.map((item) => ({
+      ...item,
+      url: processSearchResultUrl(item.url),
+    })),
   ).current;
   const resultsFooterComponent = useMemo(
     () =>

package/lib/theme/SearchPage/index.js

@@ -5,26 +5,29 @@
  * 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 React, {useEffect, useReducer, useRef, useState} from 'react';
 import clsx from 'clsx';
-import algoliaSearch from 'algoliasearch/lite';
 import algoliaSearchHelper from 'algoliasearch-helper';
+import algoliaSearch from 'algoliasearch/lite';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import {
   HtmlClassNameProvider,
-  usePluralForm,
-  isRegexpStringMatch,
   useEvent,
+  usePluralForm,
 } from '@docusaurus/theme-common';
 import {
-  useTitleFormatter,
   useSearchPage,
+  useTitleFormatter,
 } from '@docusaurus/theme-common/internal';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import Translate, {translate} from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {
+  useAlgoliaThemeConfig,
+  useSearchResultUrlProcessor,
+} from '@docusaurus/theme-search-algolia/client';
 import Layout from '@theme/Layout';
 import styles from './styles.module.css';
 // Very simple pluralization: probably good enough for now
@@ -114,12 +117,12 @@ function SearchVersionSelectList({docsSearchVersionsHelpers}) {
 }
 function SearchPageContent() {
   const {
-    siteConfig: {themeConfig},
     i18n: {currentLocale},
   } = useDocusaurusContext();
   const {
-    algolia: {appId, apiKey, indexName, externalUrlRegex},
-  } = themeConfig;
+    algolia: {appId, apiKey, indexName},
+  } = useAlgoliaThemeConfig();
+  const processSearchResultUrl = useSearchResultUrlProcessor();
   const documentsFoundPlural = useDocumentsFoundPlural();
   const docsSearchVersionsHelpers = useDocsSearchVersionsHelpers();
   const {searchQuery, setSearchQuery} = useSearchPage();
@@ -191,15 +194,12 @@ function SearchPageContent() {
           _highlightResult: {hierarchy},
           _snippetResult: snippet = {},
         }) => {
-          const parsedURL = new URL(url);
           const titles = Object.keys(hierarchy).map((key) =>
             sanitizeValue(hierarchy[key].value),
           );
           return {
             title: titles.pop(),
-            url: isRegexpStringMatch(externalUrlRegex, parsedURL.href)
-              ? parsedURL.href
-              : parsedURL.pathname + parsedURL.hash,
+            url: processSearchResultUrl(url),
             summary: snippet.content
               ? `${sanitizeValue(snippet.content.value)}...`
               : '',

package/lib/validateThemeConfig.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateThemeConfig = exports.Schema = exports.DEFAULT_CONFIG = void 0;
+const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
 exports.DEFAULT_CONFIG = {
     // Enabled by default, as it makes sense in most cases
@@ -33,6 +34,18 @@ exports.Schema = utils_validation_1.Joi.object({
             .try(utils_validation_1.Joi.boolean().invalid(true), utils_validation_1.Joi.string())
             .allow(null)
             .default(exports.DEFAULT_CONFIG.searchPagePath),
+        replaceSearchResultPathname: utils_validation_1.Joi.object({
+            from: utils_validation_1.Joi.custom((from) => {
+                if (typeof from === 'string') {
+                    return (0, utils_1.escapeRegexp)(from);
+                }
+                else if (from instanceof RegExp) {
+                    return from.source;
+                }
+                throw new Error(`it should be a RegExp or a string, but received ${from}`);
+            }).required(),
+            to: utils_validation_1.Joi.string().required(),
+        }).optional(),
     })
         .label('themeConfig.algolia')
         .required()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-search-algolia",
-  "version": "0.0.0-5416",
+  "version": "0.0.0-5426",
   "description": "Algolia search component for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": [
@@ -34,13 +34,13 @@
   },
   "dependencies": {
     "@docsearch/react": "^3.2.1",
-    "@docusaurus/core": "0.0.0-5416",
-    "@docusaurus/logger": "0.0.0-5416",
-    "@docusaurus/plugin-content-docs": "0.0.0-5416",
-    "@docusaurus/theme-common": "0.0.0-5416",
-    "@docusaurus/theme-translations": "0.0.0-5416",
-    "@docusaurus/utils": "0.0.0-5416",
-    "@docusaurus/utils-validation": "0.0.0-5416",
+    "@docusaurus/core": "0.0.0-5426",
+    "@docusaurus/logger": "0.0.0-5426",
+    "@docusaurus/plugin-content-docs": "0.0.0-5426",
+    "@docusaurus/theme-common": "0.0.0-5426",
+    "@docusaurus/theme-translations": "0.0.0-5426",
+    "@docusaurus/utils": "0.0.0-5426",
+    "@docusaurus/utils-validation": "0.0.0-5426",
     "algoliasearch": "^4.14.2",
     "algoliasearch-helper": "^3.11.0",
     "clsx": "^1.2.1",
@@ -51,7 +51,7 @@
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-5416"
+    "@docusaurus/module-type-aliases": "0.0.0-5426"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "58fa9168665fa4cb70b0eb722e0d56d6e26ac8c6"
+  "gitHead": "7bc998a32c3cd26e76d79b8f7e276b06bc11af02"
 }

package/src/client/index.ts

@@ -5,4 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+export {useAlgoliaThemeConfig} from './useAlgoliaThemeConfig';
 export {useAlgoliaContextualFacetFilters} from './useAlgoliaContextualFacetFilters';
+export {useSearchResultUrlProcessor} from './useSearchResultUrlProcessor';

package/src/client/useAlgoliaThemeConfig.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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
+
+export function useAlgoliaThemeConfig(): ThemeConfig {
+  const {
+    siteConfig: {themeConfig},
+  } = useDocusaurusContext();
+  return themeConfig as ThemeConfig;
+}

package/src/client/useSearchResultUrlProcessor.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 {useCallback} from 'react';
+import {isRegexpStringMatch} from '@docusaurus/theme-common';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import {useAlgoliaThemeConfig} from './useAlgoliaThemeConfig';
+import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
+
+function replacePathname(
+  pathname: string,
+  replaceSearchResultPathname: ThemeConfig['algolia']['replaceSearchResultPathname'],
+): string {
+  return replaceSearchResultPathname
+    ? pathname.replaceAll(
+        new RegExp(replaceSearchResultPathname.from, 'g'),
+        replaceSearchResultPathname.to,
+      )
+    : pathname;
+}
+
+/**
+ * Process the search result url from Algolia to its final form, ready to be
+ * navigated to or used as a link
+ */
+export function useSearchResultUrlProcessor(): (url: string) => string {
+  const {withBaseUrl} = useBaseUrlUtils();
+  const {
+    algolia: {externalUrlRegex, replaceSearchResultPathname},
+  } = useAlgoliaThemeConfig();
+
+  return useCallback(
+    (url: string) => {
+      const parsedURL = new URL(url);
+
+      // Algolia contains an external domain => navigate to URL
+      if (isRegexpStringMatch(externalUrlRegex, parsedURL.href)) {
+        return url;
+      }
+
+      // Otherwise => transform to relative URL for SPA navigation
+      const relativeUrl = `${parsedURL.pathname + parsedURL.hash}`;
+
+      return withBaseUrl(
+        replacePathname(relativeUrl, replaceSearchResultPathname),
+      );
+    },
+    [withBaseUrl, externalUrlRegex, replaceSearchResultPathname],
+  );
+}

package/src/theme/SearchBar/index.tsx

@@ -5,20 +5,23 @@
  * 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 React, {useCallback, useMemo, useRef, useState} from 'react';
+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 {useSearchPage} from '@docusaurus/theme-common/internal';
-import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
-import {useAlgoliaContextualFacetFilters} from '@docusaurus/theme-search-algolia/client';
+import {
+  useAlgoliaContextualFacetFilters,
+  useSearchResultUrlProcessor,
+} from '@docusaurus/theme-search-algolia/client';
 import Translate from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {createPortal} from 'react-dom';
 import translations from '@theme/SearchTranslations';
 
+import type {AutocompleteState} from '@algolia/autocomplete-core';
 import type {
   DocSearchModal as DocSearchModalType,
   DocSearchModalProps,
@@ -28,7 +31,6 @@ import type {
   StoredDocSearchHit,
 } from '@docsearch/react/dist/esm/types';
 import type {SearchClient} from 'algoliasearch/lite';
-import type {AutocompleteState} from '@algolia/autocomplete-core';
 
 type DocSearchProps = Omit<
   DocSearchModalProps,
@@ -88,6 +90,7 @@ function DocSearch({
   ...props
 }: DocSearchProps) {
   const {siteMetadata} = useDocusaurusContext();
+  const processSearchResultUrl = useSearchResultUrlProcessor();
 
   const contextualSearchFacetFilters =
     useAlgoliaContextualFacetFilters() as FacetFilters;
@@ -107,7 +110,6 @@ function DocSearch({
     facetFilters,
   };
 
-  const {withBaseUrl} = useBaseUrlUtils();
   const history = useHistory();
   const searchContainer = useRef<HTMLDivElement | null>(null);
   const searchButtonRef = useRef<HTMLButtonElement>(null);
@@ -172,20 +174,10 @@ function DocSearch({
 
   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}`),
-        };
-      }),
+      items.map((item) => ({
+        ...item,
+        url: processSearchResultUrl(item.url),
+      })),
   ).current;
 
   const resultsFooterComponent: DocSearchProps['resultsFooterComponent'] =

package/src/theme/SearchPage/index.tsx

@@ -7,32 +7,33 @@
 
 /* eslint-disable jsx-a11y/no-autofocus */
 
-import React, {useEffect, useState, useReducer, useRef} from 'react';
+import React, {useEffect, useReducer, useRef, useState} from 'react';
 import clsx from 'clsx';
 
-import algoliaSearch from 'algoliasearch/lite';
 import algoliaSearchHelper from 'algoliasearch-helper';
+import algoliaSearch from 'algoliasearch/lite';
 
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import {
   HtmlClassNameProvider,
-  usePluralForm,
-  isRegexpStringMatch,
   useEvent,
+  usePluralForm,
 } from '@docusaurus/theme-common';
 import {
-  useTitleFormatter,
   useSearchPage,
+  useTitleFormatter,
 } from '@docusaurus/theme-common/internal';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import Translate, {translate} from '@docusaurus/Translate';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {
+  useAlgoliaThemeConfig,
+  useSearchResultUrlProcessor,
+} from '@docusaurus/theme-search-algolia/client';
 import Layout from '@theme/Layout';
 
-import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
-
 import styles from './styles.module.css';
 
 // Very simple pluralization: probably good enough for now
@@ -157,12 +158,12 @@ type ResultDispatcher =
 
 function SearchPageContent(): JSX.Element {
   const {
-    siteConfig: {themeConfig},
     i18n: {currentLocale},
   } = useDocusaurusContext();
   const {
-    algolia: {appId, apiKey, indexName, externalUrlRegex},
-  } = themeConfig as ThemeConfig;
+    algolia: {appId, apiKey, indexName},
+  } = useAlgoliaThemeConfig();
+  const processSearchResultUrl = useSearchResultUrlProcessor();
   const documentsFoundPlural = useDocumentsFoundPlural();
 
   const docsSearchVersionsHelpers = useDocsSearchVersionsHelpers();
@@ -245,16 +246,12 @@ function SearchPageContent(): JSX.Element {
           _highlightResult: {hierarchy: {[key: string]: {value: string}}};
           _snippetResult: {content?: {value: string}};
         }) => {
-          const parsedURL = new URL(url);
           const titles = Object.keys(hierarchy).map((key) =>
             sanitizeValue(hierarchy[key]!.value),
           );
-
           return {
             title: titles.pop()!,
-            url: isRegexpStringMatch(externalUrlRegex, parsedURL.href)
-              ? parsedURL.href
-              : parsedURL.pathname + parsedURL.hash,
+            url: processSearchResultUrl(url),
             summary: snippet.content
               ? `${sanitizeValue(snippet.content.value)}...`
               : '',

package/src/theme-search-algolia.d.ts

@@ -17,13 +17,23 @@ declare module '@docusaurus/theme-search-algolia' {
       indexName: string;
       searchParameters: {[key: string]: unknown};
       searchPagePath: string | false | null;
+      replaceSearchResultPathname?: {
+        from: string;
+        to: string;
+      };
     };
   };
   export type UserThemeConfig = DeepPartial<ThemeConfig>;
 }
 
 declare module '@docusaurus/theme-search-algolia/client' {
+  import type {ThemeConfig} from '@docusaurus/theme-search-algolia';
+
+  export function useAlgoliaThemeConfig(): ThemeConfig;
+
   export function useAlgoliaContextualFacetFilters(): [string, string[]];
+
+  export function useSearchResultUrlProcessor(): (url: string) => string;
 }
 
 declare module '@theme/SearchPage' {

package/src/validateThemeConfig.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {escapeRegexp} from '@docusaurus/utils';
 import {Joi} from '@docusaurus/utils-validation';
 import type {
   ThemeConfig,
@@ -39,6 +40,19 @@ export const Schema = Joi.object<ThemeConfig>({
       .try(Joi.boolean().invalid(true), Joi.string())
       .allow(null)
       .default(DEFAULT_CONFIG.searchPagePath),
+    replaceSearchResultPathname: Joi.object({
+      from: Joi.custom((from) => {
+        if (typeof from === 'string') {
+          return escapeRegexp(from);
+        } else if (from instanceof RegExp) {
+          return from.source;
+        }
+        throw new Error(
+          `it should be a RegExp or a string, but received ${from}`,
+        );
+      }).required(),
+      to: Joi.string().required(),
+    }).optional(),
   })
     .label('themeConfig.algolia')
     .required()