feat(algolia): add getAlgoliaFacetHits preset

bundlesize.config.json

@@ -6,7 +6,7 @@
     },
     {
       "path": "packages/autocomplete-js/dist/umd/index.production.js",
-      "maxSize": "14.25 kB"
+      "maxSize": "14.50 kB"
     },
     {
       "path": "packages/autocomplete-preset-algolia/dist/umd/index.production.js",

examples/js/app.tsx

@@ -17,6 +17,7 @@ import insightsClient from 'search-insights';
 
 import '@algolia/autocomplete-theme-classic';
 
+import { createCategoriesPlugin } from './categoriesPlugin';
 import { shortcutsPlugin } from './shortcutsPlugin';
 
 type Product = {
@@ -49,6 +50,7 @@ const querySuggestionsPlugin = createQuerySuggestionsPlugin({
   },
   categoryAttribute: 'categories',
 });
+const categoriesPlugin = createCategoriesPlugin({ searchClient });
 
 autocomplete({
   container: '#autocomplete',
@@ -60,6 +62,7 @@ autocomplete({
     algoliaInsightsPlugin,
     recentSearchesPlugin,
     querySuggestionsPlugin,
+    categoriesPlugin,
   ],
   getSources({ query, state }) {
     if (!query) {

examples/js/categoriesPlugin.tsx

@@ -0,0 +1,87 @@
+/** @jsx h */
+import {
+  AutocompletePlugin,
+  getAlgoliaFacetHits,
+  highlightHit,
+} from '@algolia/autocomplete-js';
+import { Hit } from '@algolia/client-search';
+import { SearchClient } from 'algoliasearch/lite';
+import { h, Fragment } from 'preact';
+
+type CategoryItem = {
+  label: string;
+  count: number;
+};
+
+type CreateCategoriesPluginProps = {
+  searchClient: SearchClient;
+};
+
+export function createCategoriesPlugin({
+  searchClient,
+}: CreateCategoriesPluginProps): AutocompletePlugin<CategoryItem, undefined> {
+  return {
+    getSources({ query }) {
+      return [
+        {
+          sourceId: 'categoriesPlugin',
+          getItems() {
+            return getAlgoliaFacetHits({
+              searchClient,
+              queries: [
+                {
+                  indexName: 'instant_search',
+                  params: {
+                    facetName: 'categories',
+                    facetQuery: query,
+                    maxFacetHits: query ? 3 : 10,
+                  },
+                },
+              ],
+            });
+          },
+          templates: {
+            header() {
+              return (
+                <Fragment>
+                  <span className="aa-SourceHeaderTitle">Categories</span>
+                  <div className="aa-SourceHeaderLine" />
+                </Fragment>
+              );
+            },
+            item({ item }) {
+              return (
+                <Fragment>
+                  <div className="aa-ItemIcon aa-ItemIcon--no-border">
+                    <svg
+                      viewBox="0 0 24 24"
+                      width="18"
+                      height="18"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="2"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    >
+                      <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
+                      <polyline points="3.27 6.96 12 12.01 20.73 6.96" />
+                      <line x1="12" y1="22.08" x2="12" y2="12" />
+                    </svg>
+                  </div>
+                  <div className="aa-ItemContent">
+                    <div className="aa-ItemContentTitle">
+                      {highlightHit<Hit<CategoryItem>>({
+                        hit: item as any,
+                        attribute: 'label',
+                      })}
+                    </div>
+                  </div>
+                </Fragment>
+              );
+            },
+          },
+        },
+      ];
+    },
+  };
+}

packages/autocomplete-js/src/getAlgoliaFacetHits.ts

@@ -0,0 +1,17 @@
+import {
+  getAlgoliaFacetHits as getAlgoliaFacetHitsOriginal,
+  SearchForFacetValuesParams,
+} from '@algolia/autocomplete-preset-algolia';
+
+import { version } from './version';
+
+export function getAlgoliaFacetHits({
+  searchClient,
+  queries,
+}: Pick<SearchForFacetValuesParams, 'searchClient' | 'queries'>) {
+  return getAlgoliaFacetHitsOriginal({
+    searchClient,
+    queries,
+    userAgents: [{ segment: 'autocomplete-js', version }],
+  });
+}

packages/autocomplete-js/src/index.ts

@@ -1,4 +1,5 @@
 export * from './autocomplete';
+export * from './getAlgoliaFacetHits';
 export * from './getAlgoliaHits';
 export * from './getAlgoliaResults';
 export * from './highlight';

packages/autocomplete-preset-algolia/src/index.ts

@@ -2,6 +2,8 @@ export * from './highlight/parseAlgoliaHitHighlight';
 export * from './highlight/parseAlgoliaHitReverseHighlight';
 export * from './highlight/parseAlgoliaHitReverseSnippet';
 export * from './highlight/parseAlgoliaHitSnippet';
+export * from './search/getAlgoliaFacetHits';
 export * from './search/getAlgoliaHits';
 export * from './search/getAlgoliaResults';
+export type { SearchForFacetValuesParams } from './search/searchForFacetValues';
 export type { SearchParams } from './search/search';

packages/autocomplete-preset-algolia/src/search/UserAgent.ts

@@ -0,0 +1 @@
+export type UserAgent = { segment: string; version?: string };

packages/autocomplete-preset-algolia/src/search/__tests__/search.test.ts

@@ -1,8 +1,10 @@
 import {
+  createSFFVResponse,
   createMultiSearchResponse,
   createSearchClient,
 } from '../../../../../test/utils';
 import { version } from '../../version';
+import { getAlgoliaFacetHits } from '../getAlgoliaFacetHits';
 import { getAlgoliaHits } from '../getAlgoliaHits';
 import { getAlgoliaResults } from '../getAlgoliaResults';
 
@@ -16,6 +18,24 @@ function createTestSearchClient() {
         )
       )
     ),
+    searchForFacetValues: jest.fn(() =>
+      Promise.resolve([
+        createSFFVResponse({
+          facetHits: [
+            {
+              count: 507,
+              value: 'Mobile phones',
+              highlighted: 'Mobile <em>phone</em>s',
+            },
+            {
+              count: 63,
+              value: 'Phone cases',
+              highlighted: '<em>Phone</em> cases',
+            },
+          ],
+        }),
+      ])
+    ),
   });
 }
 
@@ -256,3 +276,158 @@ describe('getAlgoliaHits', () => {
     );
   });
 });
+
+describe('getAlgoliaFacetHits', () => {
+  test('with default options', async () => {
+    const searchClient = createTestSearchClient();
+
+    const facetHits = await getAlgoliaFacetHits({
+      searchClient,
+      queries: [
+        {
+          indexName: 'indexName',
+          params: {
+            facetName: 'facetName',
+            facetQuery: 'facetQuery',
+          },
+        },
+      ],
+    });
+
+    expect(searchClient.searchForFacetValues).toHaveBeenCalledTimes(1);
+    expect(searchClient.searchForFacetValues).toHaveBeenCalledWith([
+      {
+        indexName: 'indexName',
+        params: {
+          facetName: 'facetName',
+          facetQuery: 'facetQuery',
+          highlightPreTag: '__aa-highlight__',
+          highlightPostTag: '__/aa-highlight__',
+        },
+      },
+    ]);
+    expect(facetHits).toEqual([
+      [
+        {
+          count: 507,
+          label: 'Mobile phones',
+          _highlightResult: {
+            label: {
+              value: 'Mobile <em>phone</em>s',
+            },
+          },
+        },
+        {
+          count: 63,
+          label: 'Phone cases',
+          _highlightResult: {
+            label: {
+              value: '<em>Phone</em> cases',
+            },
+          },
+        },
+      ],
+    ]);
+  });
+
+  test('with custom search parameters', async () => {
+    const searchClient = createTestSearchClient();
+
+    const facetHits = await getAlgoliaFacetHits({
+      searchClient,
+      queries: [
+        {
+          indexName: 'indexName',
+          params: {
+            facetName: 'facetName',
+            facetQuery: 'facetQuery',
+            highlightPreTag: '<em>',
+            highlightPostTag: '</em>',
+            maxFacetHits: 10,
+          },
+        },
+      ],
+    });
+
+    expect(searchClient.searchForFacetValues).toHaveBeenCalledTimes(1);
+    expect(searchClient.searchForFacetValues).toHaveBeenCalledWith([
+      {
+        indexName: 'indexName',
+        params: {
+          facetName: 'facetName',
+          facetQuery: 'facetQuery',
+          highlightPreTag: '<em>',
+          highlightPostTag: '</em>',
+          maxFacetHits: 10,
+        },
+      },
+    ]);
+    expect(facetHits).toEqual([
+      [
+        {
+          count: 507,
+          label: 'Mobile phones',
+          _highlightResult: {
+            label: {
+              value: 'Mobile <em>phone</em>s',
+            },
+          },
+        },
+        {
+          count: 63,
+          label: 'Phone cases',
+          _highlightResult: {
+            label: {
+              value: '<em>Phone</em> cases',
+            },
+          },
+        },
+      ],
+    ]);
+  });
+
+  test('attaches Algolia agent', async () => {
+    const searchClient = createTestSearchClient();
+
+    await getAlgoliaFacetHits({
+      searchClient,
+      queries: [
+        {
+          indexName: 'indexName',
+          params: {
+            facetName: 'facetName',
+            facetQuery: 'facetQuery',
+          },
+        },
+      ],
+    });
+
+    expect(searchClient.addAlgoliaAgent).toHaveBeenCalledTimes(1);
+    expect(searchClient.addAlgoliaAgent).toHaveBeenCalledWith(
+      'autocomplete-core',
+      version
+    );
+  });
+
+  test('allows custom user agents', async () => {
+    const searchClient = createTestSearchClient();
+
+    await getAlgoliaFacetHits({
+      searchClient,
+      queries: [],
+      userAgents: [{ segment: 'custom-ua', version: '1.0.0' }],
+    });
+
+    expect(searchClient.addAlgoliaAgent).toHaveBeenCalledTimes(2);
+    expect(searchClient.addAlgoliaAgent).toHaveBeenNthCalledWith(
+      1,
+      'autocomplete-core',
+      version
+    );
+    expect(searchClient.addAlgoliaAgent).toHaveBeenNthCalledWith(
+      2,
+      'custom-ua',
+      '1.0.0'
+    );
+  });
+});

packages/autocomplete-preset-algolia/src/search/getAlgoliaFacetHits.ts

@@ -0,0 +1,38 @@
+import {
+  searchForFacetValues,
+  SearchForFacetValuesParams,
+} from './searchForFacetValues';
+
+type FacetHit = {
+  label: string;
+  count: number;
+  _highlightResult: {
+    label: {
+      value: string;
+    };
+  };
+};
+
+export function getAlgoliaFacetHits({
+  searchClient,
+  queries,
+  userAgents,
+}: SearchForFacetValuesParams): Promise<FacetHit[][]> {
+  return searchForFacetValues({ searchClient, queries, userAgents }).then(
+    (response) => {
+      return response.map((result) =>
+        result.facetHits.map((facetHit) => {
+          return {
+            label: facetHit.value,
+            count: facetHit.count,
+            _highlightResult: {
+              label: {
+                value: facetHit.highlighted,
+              },
+            },
+          };
+        })
+      );
+    }
+  );
+}

packages/autocomplete-preset-algolia/src/search/search.ts

@@ -4,7 +4,8 @@ import { SearchClient } from 'algoliasearch/lite';
 import { HIGHLIGHT_PRE_TAG, HIGHLIGHT_POST_TAG } from '../constants';
 import { version } from '../version';
 
-type UserAgent = { segment: string; version?: string };
+import { UserAgent } from './UserAgent';
+
 export interface SearchParams {
   searchClient: SearchClient;
   queries: MultipleQueriesQuery[];