diff --git a/.eslintrc b/.eslintrc index be379f8..10c3f10 100644 --- a/.eslintrc +++ b/.eslintrc @@ -6,5 +6,13 @@ "@typescript-eslint/no-unused-vars": [ "off" ] - } + }, + "overrides": [ + { + "files": ["playground/pages/**"], + "rules": { + "vue/multi-word-component-names": "off" + } + } + ] } diff --git a/docs/content/2.advanced/3.docsearch.md b/docs/content/2.advanced/3.docsearch.md index 29e843f..91ed120 100644 --- a/docs/content/2.advanced/3.docsearch.md +++ b/docs/content/2.advanced/3.docsearch.md @@ -23,6 +23,10 @@ As DocSearch is an additional feature for @nuxt-modules/algolia, it needs two ad npm install @docsearch/js @docsearch/css ``` + ```bash [PNPM] + pnpm add @docsearch/js @docsearch/css + ``` + :: ## Configuration @@ -31,11 +35,9 @@ You can easily configure DocSearch usage via the `docSearch` key in the module c By default, it is set to `false`, which disables it and does not ship anything to your Nuxt app bundle. -This key is fully typed and links you to the [DocSearch API reference](https://docsearch.algolia.com/docs/api) for each key. - -```javascript +```ts // nuxt.config.ts -{ +export default defineNuxtConfig({ algolia: { apiKey: 'apiKey', applicationId: 'applicationId', @@ -44,26 +46,254 @@ This key is fully typed and links you to the [DocSearch API reference](https://d indexName: 'indexName', } } -} +}) +``` + +### Supported options + +#### `indexName` + +> `type: string` | **required** + +Your Algolia index name. + +#### `placeholder` + +> `type: string` | `default: "Search docs" | **optional** + +The placeholder of the input of the DocSearch pop-up modal. + +#### `searchParameters` + +> `type: SearchParameters` | **optional** + +The [Algolia Search Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/). + +#### `disableUserPersonalization` + +> `type: boolean` | `default: false` | **optional** + +Disable saving recent searches and favorites to the local storage. + +#### `initialQuery` + +> `type: string` | **optional** + +The search input initial query. + +#### `translations` + +> `type: Partial` | `default: docSearchTranslations` | **optional** + +Allow translations of any raw text and aria-labels present in the DocSearch button or modal components. + +
docSearchTranslations +
+ +```ts +const translations: DocSearchTranslations = { + button: { + buttonText: 'Search', + buttonAriaLabel: 'Search', + }, + modal: { + searchBox: { + resetButtonTitle: 'Clear the query', + resetButtonAriaLabel: 'Clear the query', + cancelButtonText: 'Cancel', + cancelButtonAriaLabel: 'Cancel', + }, + startScreen: { + recentSearchesTitle: 'Recent', + noRecentSearchesText: 'No recent searches', + saveRecentSearchButtonTitle: 'Save this search', + removeRecentSearchButtonTitle: 'Remove this search from history', + favoriteSearchesTitle: 'Favorite', + removeFavoriteSearchButtonTitle: 'Remove this search from favorites', + }, + errorScreen: { + titleText: 'Unable to fetch results', + helpText: 'You might want to check your network connection.', + }, + footer: { + selectText: 'to select', + selectKeyAriaLabel: 'Enter key', + navigateText: 'to navigate', + navigateUpKeyAriaLabel: 'Arrow up', + navigateDownKeyAriaLabel: 'Arrow down', + closeText: 'to close', + closeKeyAriaLabel: 'Escape key', + searchByText: 'Search by', + }, + noResultsScreen: { + noResultsText: 'No results for', + suggestedQueryText: 'Try searching for', + reportMissingResultsText: 'Believe this query should return results?', + reportMissingResultsLinkText: 'Let us know.', + }, + }, +}; ``` -You can find a list of every supported parameters by looking at the type definition ([DocSearchOptions](https://github.com/nuxt-modules/algolia/tree/main/src/types.ts)). +
+
+ +#### `facetFilters` + +> `type: string` | **optional** + +The facetFilters to use in your search parameters. This is local shorthand and provided by `@nuxtjs/algolia`. + +This will be overwritten if you add `facetFilters` into your `searchOptions` object. + +See [algolia facetFilters](https://www.algolia.com/doc/api-reference/api-parameters/facetFilters/) + +#### `langAttribute` + +> `type: string` | **optional** -## Usage +The language to prefix all your facetFilters with. This will be overwritten if you add `facetFilters` into your `searchOptions` object. This is local shorthand and provided by @nuxtjs/algolia. + +#### `lang` + +> `type: string` | `default: 'en'` | **optional** + +Default language to be used on the Algolia DocSearch client. + +## Component Usage You can easily add the component anywhere in your app like this: ```vue +``` + +The component will use the configuration values declared in `nuxt.config.ts`. + +You can pass the configuration directly to the component as well if it's more convenient for you, like this: + +```vue + ``` -`options` key is optional. +::alert{type="info"} -The component will try to resolve the configuration by itself via `useRuntimeConfig`. +If a specific option is set in both `nuxt.config.ts` and as a component prop, the latter takes precedence. -If you want to overwrite the config from your `nuxt.config`, you can pass the object via the prop. +:: + +### Additional Component Props + +These options are only available as component props. + +#### `transformItems` + +> `type: function` | `default: items => items` | **optional** + +Receives the items from the search response, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them. + +```vue + +``` + +#### `hitComponent` + +> `type: ({ hit, children }) => JSX.Element` | `default: Hit` | **optional** + +The component to display each item. + +See the [default implementation](https://github.com/algolia/docsearch/blob/main/packages/docsearch-react/src/Hit.tsx). + +#### `transformSearchClient` + +> `type: function` | `default: searchClient => searchClient` | **optional** + +Useful for transforming the [Algolia Search Client](https://www.algolia.com/doc/api-client/getting-started/what-is-the-api-client/javascript/?client=javascript), for example to debounce search queries: + +```vue + + + +``` + +#### `navigator` + +> `type: Navigator` | **optional** + +An implementation of [Algolia Autocomplete](https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/)’s Navigator API to redirect the user when opening a link. + +Learn more on the [Navigator API](https://www.algolia.com/doc/ui-libraries/autocomplete/core-concepts/keyboard-navigation/) documentation. + +#### `getMissingResultsUrl` + +> `type: ({ query: string }) => string` | **optional** + +Function to return the URL of your documentation repository. + +```vue + + + +``` ## Theming diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts index a496df7..b62ef6b 100644 --- a/playground/nuxt.config.ts +++ b/playground/nuxt.config.ts @@ -15,13 +15,15 @@ export default defineNuxtConfig({ } }, algolia: { - // apiKey: process.env.ALGOLIA_API_KEY, - // applicationId: process.env.ALGOLIA_APPLICATION_ID, + apiKey: process.env.ALGOLIA_API_KEY ?? '599cec31baffa4868cae4e79f180729b', + applicationId: process.env.ALGOLIA_APPLICATION_ID ?? 'R2IYF7ETH7', lite: false, // by default set to 'true' cache: true, docSearch: { - indexName: process.env.ALGOLIA_DOCSEARCH_INDEX_NAME ?? 'indexName', - facetFilters: process.env.ALGOLIA_DOCSEARCH_FACET_FILTERS ?? '' + indexName: process.env.ALGOLIA_DOCSEARCH_INDEX_NAME ?? 'docsearch', + searchParameters: { + facetFilters: [] + } }, instantSearch: { theme: 'algolia' diff --git a/playground/pages/docsearch.vue b/playground/pages/docsearch.vue new file mode 100644 index 0000000..62f36e9 --- /dev/null +++ b/playground/pages/docsearch.vue @@ -0,0 +1,39 @@ + + + diff --git a/playground/pages/docsearch/debounce-search.vue b/playground/pages/docsearch/debounce-search.vue new file mode 100644 index 0000000..b575fa0 --- /dev/null +++ b/playground/pages/docsearch/debounce-search.vue @@ -0,0 +1,38 @@ + + + diff --git a/playground/pages/docsearch/index.vue b/playground/pages/docsearch/index.vue new file mode 100644 index 0000000..f46cf5e --- /dev/null +++ b/playground/pages/docsearch/index.vue @@ -0,0 +1,14 @@ + diff --git a/playground/pages/docsearch/transform-items.vue b/playground/pages/docsearch/transform-items.vue new file mode 100644 index 0000000..18d1edf --- /dev/null +++ b/playground/pages/docsearch/transform-items.vue @@ -0,0 +1,20 @@ + + + diff --git a/playground/pages/index.vue b/playground/pages/index.vue index f043087..751f524 100644 --- a/playground/pages/index.vue +++ b/playground/pages/index.vue @@ -1,5 +1,5 @@ diff --git a/src/types.ts b/src/types.ts index d907e99..5671eb1 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,9 +1,7 @@ -import { AutocompleteOptions, AutocompleteState } from '@algolia/autocomplete-core' import { DocSearchTranslations } from '@docsearch/react' -import { DocSearchHit, InternalDocSearchHit, StoredDocSearchHit } from '@docsearch/react/dist/esm/types' +import { InternalDocSearchHit, StoredDocSearchHit } from '@docsearch/react/dist/esm/types' import type { SearchIndex } from 'algoliasearch' -import { SearchClient } from 'algoliasearch/lite' export interface AlgoliaIndices {} @@ -936,31 +934,6 @@ export interface DocSearchOptions { * {@link https://docsearch.algolia.com/docs/api#searchparameters} */ searchParameters?: SearchOptions; - /** - * Receives the items from the search response, and is called before displaying them. - * Should return a new array with the same shape as the original array. - * Useful for mapping over the items to transform, and remove or reorder them. - * - * {@link https://docsearch.algolia.com/docs/api#transformitems} - */ - transformItems?: (items: DocSearchHit[]) => DocSearchHit[]; - /** - * The component to display each item. - * - * {@link https://docsearch.algolia.com/docs/api#hitcomponent} - * {@link https://github.com/algolia/docsearch/blob/next/packages/docsearch-react/src/Hit.tsx} - */ - hitComponent?: (props: { - hit: InternalDocSearchHit | StoredDocSearchHit; - // Avoid importing React types there - children: any; // React.ReactNode; - }) => JSX.Element; - /** - * Useful for transforming the Algolia Search Client, for example to debounce search queries. - * - * {@link https://docsearch.algolia.com/docs/api#transformsearchclient} - */ - transformSearchClient?: (searchClient: SearchClient) => SearchClient; /** * Disable saving recent searches and favorites to the local storage. * @@ -972,25 +945,11 @@ export interface DocSearchOptions { * {@link https://docsearch.algolia.com/docs/api#initialquery} */ initialQuery?: string; - /** - * An implementation of Algolia Autocomplete’s Navigator API to redirect the user when opening a link. - * - * {@link https://docsearch.algolia.com/docs/api#navigator} - */ - navigator?: AutocompleteOptions['navigator']; /** * Allow translations of any raw text and aria-labels present in the DocSearch button or modal components. * {@link https://docsearch.algolia.com/docs/api#translations} */ translations?: DocSearchTranslations; - /** - * Function to return the URL of your documentation repository. - * When provided, an informative message wrapped with your link will be displayed on no results searches. - * The default text can be changed using the translations property. - * - * {@link https://docsearch.algolia.com/docs/api#getmissingresultsurl} - */ - getMissingResultsUrl?: (opts: { query: string }) => string; /** * The facetFilters to use in your search parameters. * This is local shorthand and provided by @nuxtjs/algolia. @@ -1011,3 +970,36 @@ export interface DocSearchOptions { */ lang?: string } + +export type HitComponentFunc = (props: { + hit: InternalDocSearchHit | StoredDocSearchHit; + // Avoid importing React types there + children: any; // React.ReactNode; +}) => JSX.Element + +export enum InstantSearchThemes { + 'reset', + 'algolia', + 'satellite', +} + +interface Indexer { + storyblok: { + accessToken: string, + algoliaAdminApiKey: string, + indexName: string, + secret: string; + } +} + +export interface ModuleBaseOptions { + applicationId: string; + apiKey: string; + globalIndex: string; + lite?: boolean; + cache?: boolean; + instantSearch?: boolean | { theme: keyof typeof InstantSearchThemes }; + recommend?: boolean; + docSearch?: Partial; + indexer?: Indexer; +}