feat(hooks): document query suggestions (#396)

dhayab · sarahdayan · web-flow · commit e34bde43e1e6 · 2022-07-07T14:49:41.000+02:00
Co-authored-by: Sarah Dayan &lt;5370675+sarahdayan@users.noreply.github.com&gt;
diff --git a/react-instantsearch-hooks/query-suggestions/.editorconfig b/react-instantsearch-hooks/query-suggestions/.editorconfig
@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
diff --git a/react-instantsearch-hooks/query-suggestions/.gitignore b/react-instantsearch-hooks/query-suggestions/.gitignore
@@ -0,0 +1,23 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+.parcel-cache
+*.local
+
+# Editor directories and files
+.vscode
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
diff --git a/react-instantsearch-hooks/query-suggestions/.prettierrc b/react-instantsearch-hooks/query-suggestions/.prettierrc
@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "proseWrap": "never",
+  "trailingComma": "es5"
+}
diff --git a/react-instantsearch-hooks/query-suggestions/README.md b/react-instantsearch-hooks/query-suggestions/README.md
@@ -0,0 +1,19 @@
+# query-suggestions
+
+_This project was generated with [create-instantsearch-app](https://github.com/algolia/create-instantsearch-app) by [Algolia](https://algolia.com)._
+
+## Get started
+
+To run this project locally, install the dependencies and run the local server:
+
+```sh
+npm install
+npm start
+```
+
+Alternatively, you may use [Yarn](https://http://yarnpkg.com/):
+
+```sh
+yarn
+yarn start
+```
diff --git a/react-instantsearch-hooks/query-suggestions/favicon.png b/react-instantsearch-hooks/query-suggestions/favicon.png
diff --git a/react-instantsearch-hooks/query-suggestions/index.html b/react-instantsearch-hooks/query-suggestions/index.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, shrink-to-fit=no"
+    />
+
+    <link rel="shortcut icon" href="favicon.png">
+
+    <!--
+    Do not use @7 in production, use a complete version like x.x.x, see website for latest version:
+    https://www.algolia.com/doc/guides/building-search-ui/installation/react/#load-the-style
+    -->
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/instantsearch.css@7/themes/algolia-min.css"
+    />
+
+    <title>query-suggestions</title>
+  </head>
+
+  <body>
+    <noscript> You need to enable JavaScript to run this app. </noscript>
+
+    <div id="root"></div>
+
+    <script type="module" src="src/index.tsx"></script>
+  </body>
+</html>
diff --git a/react-instantsearch-hooks/query-suggestions/package.json b/react-instantsearch-hooks/query-suggestions/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "query-suggestions",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "parcel index.html",
+    "build": "parcel build index.html"
+  },
+  "dependencies": {
+    "@algolia/autocomplete-js": "1.7.0",
+    "@algolia/autocomplete-plugin-query-suggestions": "1.7.0",
+    "@algolia/autocomplete-theme-classic": "1.7.0",
+    "algoliasearch": "4",
+    "instantsearch.js": "4.40.5",
+    "react": "17.0.2",
+    "react-dom": "17.0.2",
+    "react-instantsearch-hooks-web": "6.29.0"
+  },
+  "devDependencies": {
+    "@types/react": "17.0.45",
+    "parcel": "2.5.0"
+  }
+}
diff --git a/react-instantsearch-hooks/query-suggestions/src/App.css b/react-instantsearch-hooks/query-suggestions/src/App.css
@@ -0,0 +1,35 @@
+body,
+h1 {
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica,
+    Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+}
+
+.container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 1rem;
+}
+
+.current-refinements {
+  display: flex;
+  align-items: center;
+  padding: 1rem 0;
+  min-height: 64px;
+}
+
+@media screen and (max-width: 768px) {
+  .ais-Hits .ais-Hits-item {
+    width: calc(50% - 1rem);
+  }
+}
+
+@media screen and (max-width: 480px) {
+  .ais-Hits .ais-Hits-item {
+    width: 100%;
+  }
+}
diff --git a/react-instantsearch-hooks/query-suggestions/src/App.tsx b/react-instantsearch-hooks/query-suggestions/src/App.tsx
@@ -0,0 +1,45 @@
+import {
+  Configure,
+  CurrentRefinements,
+  Highlight,
+  Hits,
+  InstantSearch,
+} from 'react-instantsearch-hooks-web';
+
+import './App.css';
+
+import type { Hit } from 'instantsearch.js';
+
+import { SearchBoxWithSuggestions } from './SearchBoxWithSuggestions';
+import { searchClient } from './searchClient';
+
+export function App() {
+  return (
+    <div className="container">
+      <InstantSearch searchClient={searchClient} indexName="instant_search">
+        <Configure hitsPerPage={16} />
+
+        <SearchBoxWithSuggestions />
+
+        <CurrentRefinements
+          className="current-refinements"
+          includedAttributes={['query', 'categories']}
+        />
+
+        <Hits hitComponent={Hit} />
+      </InstantSearch>
+    </div>
+  );
+}
+
+type HitProps = {
+  hit: Hit;
+};
+
+function Hit({ hit }: HitProps) {
+  return (
+    <article>
+      <Highlight attribute="name" hit={hit} />
+    </article>
+  );
+}
diff --git a/react-instantsearch-hooks/query-suggestions/src/Autocomplete.tsx b/react-instantsearch-hooks/query-suggestions/src/Autocomplete.tsx
@@ -0,0 +1,31 @@
+import { createElement, Fragment, useEffect, useRef } from 'react';
+import { render } from 'react-dom';
+
+import { autocomplete } from '@algolia/autocomplete-js';
+
+import type { AutocompleteOptions } from '@algolia/autocomplete-js';
+import type { BaseItem } from '@algolia/autocomplete-core';
+
+import '@algolia/autocomplete-theme-classic';
+
+type AutocompleteProps = Partial<AutocompleteOptions<BaseItem>>;
+
+export function Autocomplete(props: AutocompleteProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) {
+      return;
+    }
+
+    const search = autocomplete({
+      ...props,
+      container: containerRef.current,
+      renderer: { createElement, Fragment, render },
+    });
+
+    return () => search.destroy();
+  }, [props]);
+
+  return <div ref={containerRef} />;
+}
diff --git a/react-instantsearch-hooks/query-suggestions/src/SearchBoxWithSuggestions.tsx b/react-instantsearch-hooks/query-suggestions/src/SearchBoxWithSuggestions.tsx
@@ -0,0 +1,67 @@
+import { useCallback, useMemo } from 'react';
+
+import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
+import {
+  useInstantSearch,
+  useMenu,
+  useSearchBox,
+} from 'react-instantsearch-hooks-web';
+
+import { Autocomplete } from './Autocomplete';
+import { searchClient } from './searchClient';
+
+export function SearchBoxWithSuggestions() {
+  const { setIndexUiState } = useInstantSearch();
+  const { query } = useSearchBox();
+  useMenu({ attribute: 'categories' });
+
+  const plugins = useMemo(() => {
+    const querySuggestionsPlugin = createQuerySuggestionsPlugin({
+      indexName: 'instant_search_demo_query_suggestions',
+      searchClient,
+      categoryAttribute: [
+        'instant_search',
+        'facets',
+        'exact_matches',
+        'categories',
+      ],
+      transformSource({ source }) {
+        return {
+          ...source,
+          onSelect({ item }) {
+            setIndexUiState((indexUiState) => ({
+              ...indexUiState,
+              query: item.query,
+              menu: {
+                categories: item.__autocomplete_qsCategory || '',
+              },
+            }));
+          },
+        };
+      },
+    });
+
+    return [querySuggestionsPlugin];
+  }, []);
+
+  const initialState = useMemo(() => ({ query }), [query]);
+
+  const onReset = useCallback(
+    () =>
+      setIndexUiState((indexUiState) => ({
+        ...indexUiState,
+        query: '',
+        menu: { categories: '' },
+      })),
+    []
+  );
+
+  return (
+    <Autocomplete
+      placeholder="Search for products..."
+      plugins={plugins}
+      initialState={initialState}
+      onReset={onReset}
+    />
+  );
+}
diff --git a/react-instantsearch-hooks/query-suggestions/src/index.tsx b/react-instantsearch-hooks/query-suggestions/src/index.tsx
@@ -0,0 +1,5 @@
+import ReactDOM from 'react-dom';
+
+import { App } from './App';
+
+ReactDOM.render(<App />, document.getElementById('root'));
diff --git a/react-instantsearch-hooks/query-suggestions/src/searchClient.ts b/react-instantsearch-hooks/query-suggestions/src/searchClient.ts
@@ -0,0 +1,6 @@
+import algoliasearch from 'algoliasearch/lite';
+
+export const searchClient = algoliasearch(
+  'latency',
+  '6be0576ff61c053d5f9a3225e2a90f76'
+);
diff --git a/react-instantsearch-hooks/query-suggestions/yarn.lock b/react-instantsearch-hooks/query-suggestions/yarn.lock
