feat(voice): allow custom voice helper

src/components/VoiceSearch/VoiceSearch.tsx

@@ -4,11 +4,7 @@ import { h } from 'preact';
 import Template from '../Template/Template';
 
 import { VoiceSearchTemplates } from '../../widgets/voice-search/voice-search';
-
-import {
-  VoiceListeningState,
-  ToggleListening,
-} from '../../lib/voiceSearchHelper';
+import { VoiceListeningState } from '../../lib/voiceSearchHelper/types';
 
 export type VoiceSearchComponentCSSClasses = {
   root: string;
@@ -20,7 +16,7 @@ export type VoiceSearchProps = {
   cssClasses: VoiceSearchComponentCSSClasses;
   isBrowserSupported: boolean;
   isListening: boolean;
-  toggleListening: ToggleListening;
+  toggleListening: () => void;
   voiceListeningState: VoiceListeningState;
   templates: VoiceSearchTemplates;
 };

src/connectors/voice-search/__tests__/connectVoiceSearch-test.js

@@ -3,11 +3,14 @@ import connectVoiceSearch from '../connectVoiceSearch';
 
 jest.mock('../../../lib/voiceSearchHelper', () => {
   return ({ onStateChange, onQueryChange }) => {
+    let isListening = false;
     return {
       getState: () => {},
       isBrowserSupported: () => true,
-      isListening: () => false,
-      toggleListening: () => {},
+      isListening: () => isListening,
+      startListening: () => {
+        isListening = !isListening;
+      },
       dispose: jest.fn(),
       // ⬇️ for test
       changeState: () => onStateChange(),
@@ -65,6 +68,28 @@ See documentation: https://www.algolia.com/doc/api-reference/widgets/voice-searc
         })
       );
     });
+
+    it('creates custom voice helper', () => {
+      const voiceHelper = {
+        isBrowserSupported: () => true,
+        dispose: () => {},
+        getState: () => ({
+          isSpeechFinal: true,
+          status: 'askingPermission',
+          transcript: '',
+        }),
+        isListening: () => true,
+        toggleListening: () => {},
+      };
+
+      const { widget } = getInitializedWidget({
+        widgetParams: {
+          createVoiceSearchHelper: () => voiceHelper,
+        },
+      });
+
+      expect(widget._voiceSearchHelper).toBe(voiceHelper);
+    });
   });
 
   it('calls renderFn during init and render', () => {

src/connectors/voice-search/connectVoiceSearch.ts

@@ -5,10 +5,11 @@ import {
   noop,
 } from '../../lib/utils';
 import { Renderer, RendererOptions, WidgetFactory } from '../../types';
-import createVoiceSearchHelper, {
+import builtInCreateVoiceSearchHelper from '../../lib/voiceSearchHelper';
+import {
+  CreateVoiceSearchHelper,
   VoiceListeningState,
-  ToggleListening,
-} from '../../lib/voiceSearchHelper';
+} from '../../lib/voiceSearchHelper/types';
 
 const withUsage = createDocumentationMessageGenerator({
   name: 'voice-search',
@@ -21,12 +22,13 @@ export type VoiceSearchConnectorParams = {
   additionalQueryParameters?: (params: {
     query: string;
   }) => PlainSearchParameters | void;
+  createVoiceSearchHelper?: CreateVoiceSearchHelper;
 };
 
 export type VoiceSearchRendererOptions<TVoiceSearchWidgetParams> = {
   isBrowserSupported: boolean;
   isListening: boolean;
-  toggleListening: ToggleListening;
+  toggleListening: () => void;
   voiceListeningState: VoiceListeningState;
 } & RendererOptions<TVoiceSearchWidgetParams>;
 
@@ -58,15 +60,25 @@ const connectVoiceSearch: VoiceSearchConnector = (
       voiceSearchHelper: {
         isBrowserSupported,
         isListening,
-        toggleListening,
+        startListening,
+        stopListening,
         getState,
       },
     }): void => {
       renderFn(
         {
           isBrowserSupported: isBrowserSupported(),
           isListening: isListening(),
-          toggleListening,
+          toggleListening() {
+            if (!isBrowserSupported()) {
+              return;
+            }
+            if (isListening()) {
+              stopListening();
+            } else {
+              startListening();
+            }
+          },
           voiceListeningState: getState(),
           widgetParams,
           instantSearchInstance,
@@ -79,6 +91,7 @@ const connectVoiceSearch: VoiceSearchConnector = (
       searchAsYouSpeak = false,
       language,
       additionalQueryParameters,
+      createVoiceSearchHelper = builtInCreateVoiceSearchHelper,
     } = widgetParams;
 
     return {

src/lib/voiceSearchHelper/__tests__/index-test.ts

@@ -94,7 +94,7 @@ describe('VoiceSearchHelper', () => {
       onStateChange,
     });
 
-    voiceSearchHelper.toggleListening();
+    voiceSearchHelper.startListening();
     expect(onStateChange).toHaveBeenCalledTimes(1);
     expect(voiceSearchHelper.getState().status).toEqual('askingPermission');
     simulateListener.start();
@@ -132,7 +132,7 @@ describe('VoiceSearchHelper', () => {
       onStateChange,
     });
 
-    voiceSearchHelper.toggleListening();
+    voiceSearchHelper.startListening();
     expect(onStateChange).toHaveBeenCalledTimes(1);
     expect(voiceSearchHelper.getState().status).toEqual('askingPermission');
     simulateListener.start();
@@ -169,7 +169,7 @@ describe('VoiceSearchHelper', () => {
       onQueryChange,
       onStateChange,
     });
-    voiceSearchHelper.toggleListening();
+    voiceSearchHelper.startListening();
     expect(voiceSearchHelper.getState().status).toEqual('askingPermission');
     simulateListener.error({
       error: 'not-allowed',
@@ -187,7 +187,7 @@ describe('VoiceSearchHelper', () => {
       onQueryChange: () => {},
       onStateChange: () => {},
     });
-    voiceSearchHelper.toggleListening();
+    voiceSearchHelper.startListening();
     voiceSearchHelper.dispose();
     expect(stop).toHaveBeenCalledTimes(1);
   });
@@ -202,8 +202,8 @@ describe('VoiceSearchHelper', () => {
       onStateChange,
     });
 
-    voiceSearchHelper.toggleListening();
-    voiceSearchHelper.toggleListening();
+    voiceSearchHelper.startListening();
+    voiceSearchHelper.stopListening();
     expect(voiceSearchHelper.getState().status).toBe('finished');
   });
 });

src/lib/voiceSearchHelper/index.ts

@@ -1,41 +1,11 @@
-export type VoiceSearchHelperParams = {
-  searchAsYouSpeak: boolean;
-  language?: string;
-  onQueryChange: (query: string) => void;
-  onStateChange: () => void;
-};
-
-export type Status =
-  | 'initial'
-  | 'askingPermission'
-  | 'waiting'
-  | 'recognizing'
-  | 'finished'
-  | 'error';
-
-export type VoiceListeningState = {
-  status: Status;
-  transcript: string;
-  isSpeechFinal: boolean;
-  errorCode?: SpeechRecognitionErrorCode;
-};
+import { CreateVoiceSearchHelper, Status, VoiceListeningState } from './types';
 
-export type VoiceSearchHelper = {
-  getState: () => VoiceListeningState;
-  isBrowserSupported: () => boolean;
-  isListening: () => boolean;
-  toggleListening: () => void;
-  dispose: () => void;
-};
-
-export type ToggleListening = () => void;
-
-export default function createVoiceSearchHelper({
+const createVoiceSearchHelper: CreateVoiceSearchHelper = function createVoiceSearchHelper({
   searchAsYouSpeak,
   language,
   onQueryChange,
   onStateChange,
-}: VoiceSearchHelperParams): VoiceSearchHelper {
+}) {
   const SpeechRecognitionAPI: new () => SpeechRecognition =
     (window as any).webkitSpeechRecognition ||
     (window as any).SpeechRecognition;
@@ -139,22 +109,14 @@ export default function createVoiceSearchHelper({
     resetState('finished');
   };
 
-  const toggleListening = (): void => {
-    if (!isBrowserSupported()) {
-      return;
-    }
-    if (isListening()) {
-      stop();
-    } else {
-      start();
-    }
-  };
-
   return {
     getState,
     isBrowserSupported,
     isListening,
-    toggleListening,
+    startListening: start,
+    stopListening: stop,
     dispose,
   };
-}
+};
+
+export default createVoiceSearchHelper;

src/lib/voiceSearchHelper/types.ts

@@ -0,0 +1,34 @@
+export type Status =
+  | 'initial'
+  | 'askingPermission'
+  | 'waiting'
+  | 'recognizing'
+  | 'finished'
+  | 'error';
+
+export type VoiceListeningState = {
+  status: Status;
+  transcript: string;
+  isSpeechFinal: boolean;
+  errorCode?: string;
+};
+
+export type VoiceSearchHelperParams = {
+  searchAsYouSpeak: boolean;
+  language?: string;
+  onQueryChange: (query: string) => void;
+  onStateChange: () => void;
+};
+
+export type VoiceSearchHelper = {
+  getState: () => VoiceListeningState;
+  isBrowserSupported: () => boolean;
+  isListening: () => boolean;
+  startListening: () => void;
+  stopListening: () => void;
+  dispose: () => void;
+};
+
+export type CreateVoiceSearchHelper = (
+  params: VoiceSearchHelperParams
+) => VoiceSearchHelper;

src/widgets/voice-search/__tests__/voice-search-test.ts

@@ -12,7 +12,8 @@ import {
 import { createSingleSearchResponse } from '../../../../test/mock/createAPIResponse';
 import { castToJestMock } from '../../../../test/utils/castToJestMock';
 import { Widget } from '../../../types';
-import voiceSearch from '../voice-search';
+import voiceSearch, { VoiceSearchWidgetParams } from '../voice-search';
+import { VoiceSearchHelper } from '../../../lib/voiceSearchHelper/types';
 
 const render = castToJestMock(preactRender);
 
@@ -31,7 +32,9 @@ type DefaultSetupWrapper = {
   widgetRender: (helper: Helper) => void;
 };
 
-function defaultSetup(opts = {}): DefaultSetupWrapper {
+function defaultSetup(
+  opts: Omit<VoiceSearchWidgetParams, 'container'> = {}
+): DefaultSetupWrapper {
   const container = document.createElement('div');
   const widget = voiceSearch({ container, ...opts });
 
@@ -92,6 +95,29 @@ describe('voiceSearch()', () => {
 See documentation: https://www.algolia.com/doc/api-reference/widgets/voice-search/js/"
 `);
     });
+
+    it('creates custom voice helper', () => {
+      const voiceHelper: VoiceSearchHelper = {
+        isBrowserSupported: () => true,
+        dispose: () => {},
+        getState: () => ({
+          isSpeechFinal: true,
+          status: 'askingPermission',
+          transcript: '',
+        }),
+        isListening: () => true,
+        startListening: () => {},
+        stopListening: () => {},
+      };
+
+      const { widgetInit, widget } = defaultSetup({
+        createVoiceSearchHelper: () => voiceHelper,
+      });
+
+      widgetInit(helper);
+
+      expect((widget as any)._voiceSearchHelper).toBe(voiceHelper);
+    });
   });
 
   describe('Rendering', () => {

src/widgets/voice-search/voice-search.tsx

@@ -16,6 +16,7 @@ import VoiceSearch, {
 } from '../../components/VoiceSearch/VoiceSearch';
 import defaultTemplates from './defaultTemplates';
 import { WidgetFactory, Template } from '../../types';
+import { CreateVoiceSearchHelper } from '../../lib/voiceSearchHelper/types';
 
 const withUsage = createDocumentationMessageGenerator({ name: 'voice-search' });
 const suit = component('VoiceSearch');
@@ -40,7 +41,7 @@ export type VoiceSearchTemplates = {
   status: Template<VoiceSearchTemplateProps>;
 };
 
-type VoiceSearchWidgetParams = {
+export type VoiceSearchWidgetParams = {
   container: string | HTMLElement;
   cssClasses?: Partial<VoiceSearchCSSClasses>;
   templates?: Partial<VoiceSearchTemplates>;
@@ -49,6 +50,7 @@ type VoiceSearchWidgetParams = {
   additionalQueryParameters?: (params: {
     query: string;
   }) => PlainSearchParameters | void;
+  createVoiceSearchHelper?: CreateVoiceSearchHelper;
 };
 
 type VoiceSearchRendererWidgetParams = {
@@ -89,6 +91,7 @@ const voiceSearch: VoiceSearch = (
     searchAsYouSpeak = false,
     language,
     additionalQueryParameters,
+    createVoiceSearchHelper,
   } = {} as VoiceSearchWidgetParams
 ) => {
   if (!container) {
@@ -114,6 +117,7 @@ const voiceSearch: VoiceSearch = (
     searchAsYouSpeak,
     language,
     additionalQueryParameters,
+    createVoiceSearchHelper,
   });
 };