feat(plugins): introduce Insights plugin (#373)

.circleci/config.yml

@@ -27,13 +27,15 @@ aliases:
       mkdir -p packages/autocomplete-core/dist
       mkdir -p packages/autocomplete-js/dist
       mkdir -p packages/autocomplete-preset-algolia/dist
+      mkdir -p packages/autocomplete-plugin-algolia-insights/dist
       mkdir -p packages/autocomplete-plugin-recent-searches/dist
       mkdir -p packages/autocomplete-plugin-query-suggestions/dist
 
       cp -R /tmp/workspace/packages/autocomplete-shared/dist packages/autocomplete-shared
       cp -R /tmp/workspace/packages/autocomplete-core/dist packages/autocomplete-core
       cp -R /tmp/workspace/packages/autocomplete-js/dist packages/autocomplete-js
       cp -R /tmp/workspace/packages/autocomplete-preset-algolia/dist packages/autocomplete-preset-algolia
+      cp -R /tmp/workspace/packages/autocomplete-plugin-algolia-insights/dist packages/autocomplete-plugin-algolia-insights
       cp -R /tmp/workspace/packages/autocomplete-plugin-recent-searches/dist packages/autocomplete-plugin-recent-searches
       cp -R /tmp/workspace/packages/autocomplete-plugin-query-suggestions/dist packages/autocomplete-plugin-query-suggestions
 
@@ -69,13 +71,15 @@ jobs:
             mkdir -p /tmp/workspace/packages/autocomplete-core/dist
             mkdir -p /tmp/workspace/packages/autocomplete-js/dist
             mkdir -p /tmp/workspace/packages/autocomplete-preset-algolia/dist
+            mkdir -p /tmp/workspace/packages/autocomplete-plugin-algolia-insights/dist
             mkdir -p /tmp/workspace/packages/autocomplete-plugin-recent-searches/dist
             mkdir -p /tmp/workspace/packages/autocomplete-plugin-query-suggestions/dist
 
             cp -R packages/autocomplete-shared/dist /tmp/workspace/packages/autocomplete-shared
             cp -R packages/autocomplete-core/dist /tmp/workspace/packages/autocomplete-core
             cp -R packages/autocomplete-js/dist /tmp/workspace/packages/autocomplete-js
             cp -R packages/autocomplete-preset-algolia/dist /tmp/workspace/packages/autocomplete-preset-algolia
+            cp -R packages/autocomplete-plugin-algolia-insights/dist /tmp/workspace/packages/autocomplete-plugin-algolia-insights
             cp -R packages/autocomplete-plugin-recent-searches/dist /tmp/workspace/packages/autocomplete-plugin-recent-searches
             cp -R packages/autocomplete-plugin-query-suggestions/dist /tmp/workspace/packages/autocomplete-plugin-query-suggestions
       - persist_to_workspace:

.eslintrc.js

@@ -26,7 +26,12 @@ module.exports = {
     'new-cap': 0,
     'eslint-comments/disable-enable-pair': ['error', { allowWholeFile: true }],
     'import/extensions': 0,
-    '@typescript-eslint/camelcase': ['error', { allow: ['__autocomplete_id'] }],
+    '@typescript-eslint/camelcase': [
+      'error',
+      {
+        allow: ['__autocomplete_'],
+      },
+    ],
     // Useful to call functions like `nodeItem?.scrollIntoView()`.
     'no-unused-expressions': 0,
     complexity: 0,

README.md

@@ -29,6 +29,7 @@ You can find the Autocomplete documentation on [autocomplete.algolia.com](https:
 | [`autocomplete-preset-algolia`](packages/autocomplete-preset-algolia) | Presets to use Algolia features with Autocomplete | [Documentation](https://autocomplete.algolia.com/docs/getAlgoliaHits) |
 | [`autocomplete-plugin-recent-searches`](packages/autocomplete-plugin-recent-searches) | A plugin to add recent searches to Algolia Autocomplete | [Documentation](https://autocomplete.algolia.com/docs/createLocalStorageRecentSearchesPlugin) |
 | [`autocomplete-plugin-query-suggestions`](packages/autocomplete-plugin-query-suggestions) | A plugin to add query suggestions to Algolia Autocomplete | [Documentation](https://autocomplete.algolia.com/docs/createQuerySuggestionsPlugin) |
+| [`autocomplete-plugin-algolia-insights`](packages/autocomplete-plugin-algolia-insights) | A plugin to add Algolia Insights to Algolia Autocomplete | [Documentation](https://autocomplete.algolia.com/docs/createAlgoliaInsightsPlugin) |
 
 ## License
 

bundlesize.config.json

@@ -6,12 +6,16 @@
     },
     {
       "path": "packages/autocomplete-js/dist/umd/index.production.js",
-      "maxSize": "8.25 kB"
+      "maxSize": "8.5 kB"
     },
     {
       "path": "packages/autocomplete-preset-algolia/dist/umd/index.production.js",
       "maxSize": "1.5 kB"
     },
+    {
+      "path": "packages/autocomplete-plugin-algolia-insights/dist/umd/index.production.js",
+      "maxSize": "2 kB"
+    },
     {
       "path": "packages/autocomplete-plugin-recent-searches/dist/umd/index.production.js",
       "maxSize": "3.25 kB"

examples/js/app.ts

@@ -1,28 +1,36 @@
 import { autocomplete } from '@algolia/autocomplete-js';
+import { createAlgoliaInsightsPlugin } from '@algolia/autocomplete-plugin-algolia-insights';
 import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
 import { createLocalStorageRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';
-import algoliasearch from 'algoliasearch/lite';
+import algoliasearch from 'algoliasearch';
+import insightsClient from 'search-insights';
 
-const searchClient = algoliasearch(
-  'latency',
-  '6be0576ff61c053d5f9a3225e2a90f76'
-);
+const appId = 'latency';
+const apiKey = '6be0576ff61c053d5f9a3225e2a90f76';
+const searchClient = algoliasearch(appId, apiKey);
+insightsClient('init', { appId, apiKey });
 
+const algoliaInsightsPlugin = createAlgoliaInsightsPlugin({ insightsClient });
 const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
   key: 'search',
   limit: 3,
 });
-
 const querySuggestionsPlugin = createQuerySuggestionsPlugin({
   searchClient,
   indexName: 'instant_search_demo_query_suggestions',
   getSearchParams() {
-    return recentSearchesPlugin.data.getAlgoliaSearchParams();
+    return recentSearchesPlugin.data.getAlgoliaSearchParams({
+      clickAnalytics: true,
+    });
   },
 });
 
 autocomplete({
   container: '#autocomplete',
   openOnFocus: true,
-  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
+  plugins: [
+    algoliaInsightsPlugin,
+    recentSearchesPlugin,
+    querySuggestionsPlugin,
+  ],
 });

examples/js/package.json

@@ -11,9 +11,12 @@
   },
   "dependencies": {
     "@algolia/autocomplete-js": "1.0.0-alpha.35",
+    "@algolia/autocomplete-plugin-algolia-insights": "1.0.0-alpha.35",
     "@algolia/autocomplete-plugin-query-suggestions": "1.0.0-alpha.35",
     "@algolia/autocomplete-plugin-recent-searches": "1.0.0-alpha.35",
-    "algoliasearch": "4.6.0"
+    "@algolia/autocomplete-preset-algolia": "1.0.0-alpha.35",
+    "algoliasearch": "4.7.0",
+    "search-insights": "1.6.2"
   },
   "devDependencies": {
     "parcel-bundler": "1.12.4"

packages/autocomplete-core/src/createAutocomplete.ts

@@ -5,7 +5,12 @@ import { getDefaultProps } from './getDefaultProps';
 import { getPropGetters } from './getPropGetters';
 import { onInput } from './onInput';
 import { stateReducer } from './stateReducer';
-import { AutocompleteApi, AutocompleteOptions, BaseItem } from './types';
+import {
+  AutocompleteApi,
+  AutocompleteOptions,
+  BaseItem,
+  Subscribers,
+} from './types';
 
 export function createAutocomplete<
   TItem extends BaseItem,
@@ -17,7 +22,8 @@ export function createAutocomplete<
 ): AutocompleteApi<TItem, TEvent, TMouseEvent, TKeyboardEvent> {
   checkOptions(options);
 
-  const props = getDefaultProps(options);
+  const subscribers: Subscribers<TItem> = [];
+  const props = getDefaultProps(options, subscribers);
   const store = createStore(stateReducer, props);
 
   const {
@@ -68,6 +74,23 @@ export function createAutocomplete<
     });
   }
 
+  props.plugins.forEach((plugin) =>
+    plugin.subscribe?.({
+      setSelectedItemId,
+      setQuery,
+      setCollections,
+      setIsOpen,
+      setStatus,
+      setContext,
+      onSelect(fn) {
+        subscribers.push({ onSelect: fn });
+      },
+      onHighlight(fn) {
+        subscribers.push({ onHighlight: fn });
+      },
+    })
+  );
+
   return {
     setSelectedItemId,
     setQuery,

packages/autocomplete-core/src/getDefaultProps.ts

@@ -3,6 +3,7 @@ import {
   AutocompleteOptions,
   BaseItem,
   InternalAutocompleteOptions,
+  Subscribers,
 } from './types';
 import {
   generateAutocompleteId,
@@ -12,7 +13,8 @@ import {
 } from './utils';
 
 export function getDefaultProps<TItem extends BaseItem>(
-  props: AutocompleteOptions<TItem>
+  props: AutocompleteOptions<TItem>,
+  subscribers: Subscribers<TItem>
 ): InternalAutocompleteOptions<TItem> {
   const environment: InternalAutocompleteOptions<
     TItem
@@ -70,8 +72,14 @@ export function getDefaultProps<TItem extends BaseItem>(
             ...source,
             onSelect(params) {
               source.onSelect(params);
-              plugins.forEach((plugin) => {
-                plugin.subscribed?.onSelect?.(params);
+              subscribers.forEach((subscriber) => {
+                subscriber.onSelect?.(params);
+              });
+            },
+            onHighlight(params) {
+              source.onHighlight(params);
+              subscribers.forEach((subscriber) => {
+                subscriber.onHighlight?.(params);
               });
             },
           }))

packages/autocomplete-core/src/types/api.ts

@@ -52,14 +52,14 @@ interface ItemParams<TItem extends BaseItem> {
   source: InternalAutocompleteSource<TItem>;
 }
 
-interface OnSelectParams<TItem extends BaseItem>
+export interface OnSelectParams<TItem extends BaseItem>
   extends ItemParams<TItem>,
     AutocompleteSetters<TItem> {
   state: AutocompleteState<TItem>;
   event: any;
 }
 
-type OnHighlightParams<TItem extends BaseItem> = OnSelectParams<TItem>;
+export type OnHighlightParams<TItem extends BaseItem> = OnSelectParams<TItem>;
 
 interface OnSubmitParams<TItem extends BaseItem>
   extends AutocompleteSetters<TItem> {

packages/autocomplete-core/src/types/index.ts

@@ -4,3 +4,4 @@ export * from './plugins';
 export * from './setters';
 export * from './state';
 export * from './store';
+export * from './subscriber';

packages/autocomplete-core/src/types/plugins.ts

@@ -1,4 +1,18 @@
-import { AutocompleteOptions, AutocompleteSource, BaseItem } from './api';
+import {
+  AutocompleteOptions,
+  OnHighlightParams,
+  OnSelectParams,
+  BaseItem,
+} from './api';
+import { AutocompleteSetters } from './setters';
+
+type PluginSubscriber<TParams> = (params: TParams) => void;
+
+interface PluginSubscribeParams<TItem extends BaseItem>
+  extends AutocompleteSetters<TItem> {
+  onSelect(fn: PluginSubscriber<OnSelectParams<TItem>>): void;
+  onHighlight(fn: PluginSubscriber<OnHighlightParams<TItem>>): void;
+}
 
 export type AutocompletePlugin<
   TItem extends BaseItem,
@@ -7,14 +21,14 @@ export type AutocompletePlugin<
   Pick<AutocompleteOptions<TItem>, 'onStateChange' | 'onSubmit' | 'getSources'>
 > & {
   /**
-   * The subscribed properties are properties that are called when other sources
-   * are interacted with.
+   * Function called when Autocomplete starts.
+   *
+   * It can be used to subscribe to lifecycle hooks or to interact with the
+   * Autocomplete state and context.
    */
-  subscribed?: {
-    onSelect: AutocompleteSource<TItem>['onSelect'];
-  };
+  subscribe?(params: PluginSubscribeParams<TItem>): void;
   /**
-   * An extra plugin specific object to store variables and functions
+   * Extra plugin object to expose properties and functions as APIs.
    */
   data?: TData;
 };

packages/autocomplete-core/src/types/subscriber.ts

@@ -0,0 +1,10 @@
+import { BaseItem, OnHighlightParams, OnSelectParams } from './api';
+
+export type Subscriber<TItem extends BaseItem> = {
+  onSelect(params: OnSelectParams<TItem>): void;
+  onHighlight(params: OnHighlightParams<TItem>): void;
+};
+
+export type Subscribers<TItem extends BaseItem> = Array<
+  Partial<Subscriber<TItem>>
+>;

packages/autocomplete-plugin-algolia-insights/README.md

@@ -0,0 +1,11 @@
+# @algolia/autocomplete-plugin-algolia-insights
+
+A plugin to add Algolia Insights to Algolia Autocomplete.
+
+## Installation
+
+```sh
+yarn add @algolia/autocomplete-plugin-algolia-insights@alpha
+# or
+npm install @algolia/autocomplete-plugin-algolia-insights@alpha
+```

packages/autocomplete-plugin-algolia-insights/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@algolia/autocomplete-plugin-algolia-insights",
+  "description": "A plugin to add Algolia Insights to Algolia Autocomplete.",
+  "version": "1.0.0-alpha.35",
+  "license": "MIT",
+  "homepage": "https://github.com/algolia/autocomplete.js",
+  "repository": "algolia/autocomplete.js",
+  "author": {
+    "name": "Algolia, Inc.",
+    "url": "https://www.algolia.com"
+  },
+  "source": "src/index.ts",
+  "types": "dist/esm/index.d.ts",
+  "module": "dist/esm/index.js",
+  "main": "dist/umd/index.production.js",
+  "umd:main": "dist/umd/index.production.js",
+  "unpkg": "dist/umd/index.production.js",
+  "jsdelivr": "dist/umd/index.production.js",
+  "sideEffects": false,
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build:clean": "rm -rf ./dist",
+    "build:esm": "babel src --root-mode upward --extensions '.ts,.tsx' --out-dir dist/esm --ignore '**/*/__tests__/'",
+    "build:types": "tsc -p ./tsconfig.declaration.json --outDir ./dist/esm",
+    "build:umd": "rollup --config",
+    "build": "rm -rf ./dist && yarn build:umd && yarn build:esm && yarn build:types",
+    "on:change": "concurrently \"yarn build:esm\" \"yarn build:types\"",
+    "prepare": "yarn run build:esm",
+    "watch": "watch \"yarn on:change\" --ignoreDirectoryPattern \"/dist/\""
+  },
+  "dependencies": {
+    "@algolia/autocomplete-core": "1.0.0-alpha.35",
+    "@algolia/autocomplete-shared": "1.0.0-alpha.35"
+  },
+  "peerDependencies": {
+    "search-insights": "^1.0.0"
+  }
+}

packages/autocomplete-plugin-algolia-insights/rollup.config.js

@@ -0,0 +1,5 @@
+import { createRollupConfigs } from '../../scripts/rollup/config';
+
+import pkg from './package.json';
+
+export default createRollupConfigs({ pkg });