feat(plugin): add transformSource API

francoischalifour · francoischalifour · commit fbd9e72ee20b · 2021-02-07T11:47:36.000+01:00
This updates the plugins' API to allow complete source override, as opposed to only templates override. ## Why Users might want to override the behavior of the original source (e.g., keep the panel open on select). This wasn't possible with the previous API, which only allow to modify the template. ## API ```tsx const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({ key: 'search', limit: 3, transformSource({ source, onRemove }) { return { ...source, getItemUrl({ item }) { return `https://google.com?q=${item.query}`; }, }; }, }); const querySuggestionsPlugin = createQuerySuggestionsPlugin({ searchClient, indexName: 'instant_search_demo_query_suggestions', transformSource({ source, onTapAhead }) { return { ...source, onSelect({ setIsOpen }) { setIsOpen(true); }, getItemUrl({ item }) { return `https://google.com?q=${item.query}`; }, templates: { ...source.templates, item(params) { const { item } = params; return ( <a href={`https://google.com?q=${item.query}`} className="aa-ItemLink" > {source.templates.item(params)} </a> ); }, }, }; }, }); ```
diff --git a/packages/autocomplete-plugin-query-suggestions/src/createQuerySuggestionsPlugin.ts b/packages/autocomplete-plugin-query-suggestions/src/createQuerySuggestionsPlugin.ts
@@ -2,14 +2,11 @@ import {
   AutocompletePlugin,
   AutocompleteState,
 } from '@algolia/autocomplete-core';
-import { getAlgoliaHits, SourceTemplates } from '@algolia/autocomplete-js';
+import { AutocompleteSource, getAlgoliaHits } from '@algolia/autocomplete-js';
 import { SearchOptions } from '@algolia/client-search';
 import { SearchClient } from 'algoliasearch/lite';
 
-import {
-  getTemplates as defaultGetTemplates,
-  GetTemplatesParams,
-} from './getTemplates';
+import { getTemplates } from './getTemplates';
 import { QuerySuggestionsHit } from './types';
 
 export type CreateQuerySuggestionsPluginParams<
@@ -18,7 +15,10 @@ export type CreateQuerySuggestionsPluginParams<
   searchClient: SearchClient;
   indexName: string;
   getSearchParams?(params: { state: AutocompleteState<TItem> }): SearchOptions;
-  getTemplates?(params: GetTemplatesParams<TItem>): SourceTemplates<TItem>;
+  transformSource?(params: {
+    source: AutocompleteSource<TItem>;
+    onTapAhead(item: TItem): void;
+  }): AutocompleteSource<TItem>;
 };
 
 export function createQuerySuggestionsPlugin<
@@ -27,38 +27,43 @@ export function createQuerySuggestionsPlugin<
   searchClient,
   indexName,
   getSearchParams = () => ({}),
-  getTemplates = defaultGetTemplates,
+  transformSource = ({ source }) => source,
 }: CreateQuerySuggestionsPluginParams<TItem>): AutocompletePlugin<
   TItem,
   undefined
 > {
   return {
     getSources({ query, setQuery, refresh, state }) {
+      function onTapAhead(item: TItem) {
+        setQuery(item.query);
+        refresh();
+      }
+
+      const templates = getTemplates({ onTapAhead });
+
       return [
-        {
-          sourceId: 'querySuggestionsPlugin',
-          getItemInputValue({ item }) {
-            return item.query;
-          },
-          getItems() {
-            return getAlgoliaHits<TItem>({
-              searchClient,
-              queries: [
-                {
-                  indexName,
-                  query,
-                  params: getSearchParams({ state }),
-                },
-              ],
-            });
-          },
-          templates: getTemplates({
-            onTapAhead(item) {
-              setQuery(item.query);
-              refresh();
+        transformSource({
+          source: {
+            sourceId: 'querySuggestionsPlugin',
+            getItemInputValue({ item }) {
+              return item.query;
+            },
+            getItems() {
+              return getAlgoliaHits<TItem>({
+                searchClient,
+                queries: [
+                  {
+                    indexName,
+                    query,
+                    params: getSearchParams({ state }),
+                  },
+                ],
+              });
             },
-          }),
-        },
+            templates,
+          },
+          onTapAhead,
+        }),
       ];
     },
   };
diff --git a/packages/autocomplete-plugin-recent-searches/src/createLocalStorageRecentSearchesPlugin.ts b/packages/autocomplete-plugin-recent-searches/src/createLocalStorageRecentSearchesPlugin.ts
@@ -38,15 +38,15 @@ export type CreateRecentSearchesLocalStorageOptions<
 
 type LocalStorageRecentSearchesPluginOptions<
   TItem extends RecentSearchesItem
-> = Pick<CreateRecentSearchesPluginParams<TItem>, 'getTemplates'> &
+> = Pick<CreateRecentSearchesPluginParams<TItem>, 'transformSource'> &
   CreateRecentSearchesLocalStorageOptions<TItem>;
 
 export function createLocalStorageRecentSearchesPlugin<
   TItem extends RecentSearchesItem
 >({
   key,
   limit = 5,
-  getTemplates,
+  transformSource,
   search = defaultSearch,
 }: LocalStorageRecentSearchesPluginOptions<TItem>): AutocompletePlugin<
   TItem,
@@ -59,7 +59,7 @@ export function createLocalStorageRecentSearchesPlugin<
   });
 
   return createRecentSearchesPlugin({
-    getTemplates,
+    transformSource,
     storage,
   });
 }
diff --git a/packages/autocomplete-plugin-recent-searches/src/createRecentSearchesPlugin.ts b/packages/autocomplete-plugin-recent-searches/src/createRecentSearchesPlugin.ts
@@ -1,19 +1,12 @@
 import { AutocompletePlugin } from '@algolia/autocomplete-core';
-import { SourceTemplates } from '@algolia/autocomplete-js';
-import { MaybePromise, warn } from '@algolia/autocomplete-shared';
+import { AutocompleteSource } from '@algolia/autocomplete-js';
+import { createRef, MaybePromise, warn } from '@algolia/autocomplete-shared';
 import { SearchOptions } from '@algolia/client-search';
 
 import { createStore, RecentSearchesStorage } from './createStore';
-import {
-  getTemplates as defaultGetTemplates,
-  GetTemplatesParams,
-} from './getTemplates';
+import { getTemplates } from './getTemplates';
 import { RecentSearchesItem } from './types';
 
-type Ref<TType> = {
-  current: TType;
-};
-
 export type RecentSearchesPluginData = {
   getAlgoliaSearchParams(params?: SearchOptions): SearchOptions;
 };
@@ -22,18 +15,21 @@ export type CreateRecentSearchesPluginParams<
   TItem extends RecentSearchesItem
 > = {
   storage: RecentSearchesStorage<TItem>;
-  getTemplates?(params: GetTemplatesParams): SourceTemplates<TItem>;
+  transformSource?(params: {
+    source: AutocompleteSource<TItem>;
+    onRemove(id: string): void;
+  }): AutocompleteSource<TItem>;
 };
 
 export function createRecentSearchesPlugin<TItem extends RecentSearchesItem>({
   storage,
-  getTemplates = defaultGetTemplates,
+  transformSource = ({ source }) => source,
 }: CreateRecentSearchesPluginParams<TItem>): AutocompletePlugin<
   TItem,
   RecentSearchesPluginData
 > {
-  const store = createStore<TItem>(storage);
-  const lastItemsRef: Ref<MaybePromise<TItem[]>> = { current: [] };
+  const store = createStore(storage);
+  const lastItemsRef = createRef<MaybePromise<TItem[]>>([]);
 
   return {
     subscribe({ onSelect }) {
@@ -44,7 +40,7 @@ export function createRecentSearchesPlugin<TItem extends RecentSearchesItem>({
           store.add({
             id: inputValue,
             query: inputValue,
-          } as TItem);
+          } as any);
         }
       });
     },
@@ -55,33 +51,38 @@ export function createRecentSearchesPlugin<TItem extends RecentSearchesItem>({
         store.add({
           id: query,
           query,
-        } as TItem);
+        } as any);
       }
     },
     getSources({ query, refresh }) {
       lastItemsRef.current = store.getAll(query);
 
+      function onRemove(id: string) {
+        store.remove(id);
+        refresh();
+      }
+
+      const templates = getTemplates<any>({ onRemove });
+
       return Promise.resolve(lastItemsRef.current).then((items) => {
         if (items.length === 0) {
           return [];
         }
 
         return [
-          {
-            sourceId: 'recentSearchesPlugin',
-            getItemInputValue({ item }) {
-              return item.query;
-            },
-            getItems() {
-              return items;
-            },
-            templates: getTemplates({
-              onRemove(id) {
-                store.remove(id);
-                refresh();
+          transformSource({
+            source: {
+              sourceId: 'recentSearchesPlugin',
+              getItemInputValue({ item }) {
+                return item.query;
               },
-            }),
-          },
+              getItems() {
+                return items;
+              },
+              templates,
+            },
+            onRemove,
+          }),
         ];
       });
     },
diff --git a/packages/website/docs/createLocalStorageRecentSearchesPlugin.md b/packages/website/docs/createLocalStorageRecentSearchesPlugin.md
@@ -110,6 +110,58 @@ function search({ query, items, limit }) {
 }
 ```
 
+### `transformSource`
+
+> `(params: { source: AutocompleteSource, onRemove: () => void })`
+
+#### Example
+
+Keeping the panel open on select:
+
+```tsx
+const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
+  key: 'navbar',
+  transformSource({ source, onRemove }) {
+    return {
+      ...source,
+      onSelect({ setIsOpen }) {
+        setIsOpen(true);
+      },
+    };
+  },
+});
+```
+
+Opening a link:
+
+```tsx
+const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
+  key: 'navbar',
+  transformSource({ source, onRemove }) {
+    return {
+      ...source,
+      getItemUrl({ item }) {
+        return `https://google.com?q=${item.query}`;
+      },
+      templates: {
+        ...source.templates,
+        item(params) {
+          const { item } = params;
+          return (
+            <a
+              className="aa-ItemLink"
+              href={`https://google.com?q=${item.query}`}
+            >
+              {source.templates.item(params)}
+            </a>
+          );
+        },
+      },
+    };
+  },
+});
+```
+
 ## Returns
 
 ### `data`
diff --git a/packages/website/docs/createQuerySuggestionsPlugin.md b/packages/website/docs/createQuerySuggestionsPlugin.md
@@ -73,3 +73,57 @@ import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query
 ### `getSearchParams`
 
 > [`() => SearchParameters`](https://www.algolia.com/doc/api-reference/search-api-parameters/)
+
+### `transformSource`
+
+> `(params: { source: AutocompleteSource, onTapAhead: () => void })`
+
+#### Example
+
+Keeping the panel open on select:
+
+```tsx
+const querySuggestionsPlugin = createQuerySuggestionsPlugin({
+  searchClient,
+  indexName: 'instant_search_demo_query_suggestions',
+  transformSource({ source, onTapAhead }) {
+    return {
+      ...source,
+      onSelect({ setIsOpen }) {
+        setIsOpen(true);
+      },
+    };
+  },
+});
+```
+
+Opening a link:
+
+```tsx
+const querySuggestionsPlugin = createQuerySuggestionsPlugin({
+  searchClient,
+  indexName: 'instant_search_demo_query_suggestions',
+  transformSource({ source, onTapAhead }) {
+    return {
+      ...source,
+      getItemUrl({ item }) {
+        return `https://google.com?q=${item.query}`;
+      },
+      templates: {
+        ...source.templates,
+        item(params) {
+          const { item } = params;
+          return (
+            <a
+              className="aa-ItemLink"
+              href={`https://google.com?q=${item.query}`}
+            >
+              {source.templates.item(params)}
+            </a>
+          );
+        },
+      },
+    };
+  },
+});
+```
diff --git a/packages/website/docs/createRecentSearchesPlugin.md b/packages/website/docs/createRecentSearchesPlugin.md
