SpeechToText: Add onEnd event & stop recognition on disabled option change (#31171)

Co-authored-by: Ruslan Farkhutdinov <ruslan.farkhutdinov@devexpress.com>

Author: r-farkhutdinov

packages/devextreme-angular/src/ui/speech-to-text/index.ts

@@ -17,7 +17,7 @@ import {
 } from '@angular/core';
 
 
-import { CustomSpeechRecognizer, ContentReadyEvent, DisposingEvent, ErrorEvent, InitializedEvent, OptionChangedEvent, ResultEvent, StartClickEvent, StopClickEvent, SpeechRecognitionConfig } from 'devextreme/ui/speech_to_text';
+import { CustomSpeechRecognizer, ContentReadyEvent, DisposingEvent, EndEvent, ErrorEvent, InitializedEvent, OptionChangedEvent, ResultEvent, StartClickEvent, StopClickEvent, SpeechRecognitionConfig } from 'devextreme/ui/speech_to_text';
 import { ButtonStyle, ButtonType } from 'devextreme/common';
 
 import DxSpeechToText from 'devextreme/ui/speech_to_text';
@@ -275,6 +275,14 @@ export class DxSpeechToTextComponent extends DxComponent implements OnDestroy {
      * [descr:undefined]
     
     
+     */
+    @Output() onEnd: EventEmitter<EndEvent>;
+
+    /**
+    
+     * [descr:undefined]
+    
+    
      */
     @Output() onError: EventEmitter<ErrorEvent>;
 
@@ -476,6 +484,7 @@ export class DxSpeechToTextComponent extends DxComponent implements OnDestroy {
         this._createEventEmitters([
             { subscribe: 'contentReady', emit: 'onContentReady' },
             { subscribe: 'disposing', emit: 'onDisposing' },
+            { subscribe: 'end', emit: 'onEnd' },
             { subscribe: 'error', emit: 'onError' },
             { subscribe: 'initialized', emit: 'onInitialized' },
             { subscribe: 'optionChanged', emit: 'onOptionChanged' },

packages/devextreme-react/src/speech-to-text.ts

@@ -8,7 +8,7 @@ import dxSpeechToText, {
 import { Component as BaseComponent, IHtmlOptions, ComponentRef, NestedComponentMeta } from "./core/component";
 import NestedOption from "./core/nested-option";
 
-import type { ContentReadyEvent, DisposingEvent, ErrorEvent, InitializedEvent, ResultEvent, StartClickEvent, StopClickEvent } from "devextreme/ui/speech_to_text";
+import type { ContentReadyEvent, DisposingEvent, EndEvent, ErrorEvent, InitializedEvent, ResultEvent, StartClickEvent, StopClickEvent } from "devextreme/ui/speech_to_text";
 
 type ReplaceFieldTypes<TSource, TReplacement> = {
   [P in keyof TSource]: P extends keyof TReplacement ? TReplacement[P] : TSource[P];
@@ -17,6 +17,7 @@ type ReplaceFieldTypes<TSource, TReplacement> = {
 type ISpeechToTextOptionsNarrowedEvents = {
   onContentReady?: ((e: ContentReadyEvent) => void);
   onDisposing?: ((e: DisposingEvent) => void);
+  onEnd?: ((e: EndEvent) => void) | undefined;
   onError?: ((e: ErrorEvent) => void) | undefined;
   onInitialized?: ((e: InitializedEvent) => void);
   onResult?: ((e: ResultEvent) => void) | undefined;
@@ -43,7 +44,7 @@ const SpeechToText = memo(
         }
       ), []);
 
-      const independentEvents = useMemo(() => (["onContentReady","onDisposing","onError","onInitialized","onResult","onStartClick","onStopClick"]), []);
+      const independentEvents = useMemo(() => (["onContentReady","onDisposing","onEnd","onError","onInitialized","onResult","onStartClick","onStopClick"]), []);
 
       const expectedChildren = useMemo(() => ({
         customSpeechRecognizer: { optionName: "customSpeechRecognizer", isCollectionItem: false },

packages/devextreme-vue/src/speech-to-text.ts

@@ -6,6 +6,7 @@ import {
  CustomSpeechRecognizer,
  ContentReadyEvent,
  DisposingEvent,
+ EndEvent,
  ErrorEvent,
  InitializedEvent,
  OptionChangedEvent,
@@ -32,6 +33,7 @@ type AccessibleOptions = Pick<Properties,
   "hoverStateEnabled" |
   "onContentReady" |
   "onDisposing" |
+  "onEnd" |
   "onError" |
   "onInitialized" |
   "onOptionChanged" |
@@ -68,6 +70,7 @@ const componentConfig = {
     hoverStateEnabled: Boolean,
     onContentReady: Function as PropType<((e: ContentReadyEvent) => void)>,
     onDisposing: Function as PropType<((e: DisposingEvent) => void)>,
+    onEnd: Function as PropType<((e: EndEvent) => void)>,
     onError: Function as PropType<((e: ErrorEvent) => void)>,
     onInitialized: Function as PropType<((e: InitializedEvent) => void)>,
     onOptionChanged: Function as PropType<((e: OptionChangedEvent) => void)>,
@@ -100,6 +103,7 @@ const componentConfig = {
     "update:hoverStateEnabled": null,
     "update:onContentReady": null,
     "update:onDisposing": null,
+    "update:onEnd": null,
     "update:onError": null,
     "update:onInitialized": null,
     "update:onOptionChanged": null,

packages/devextreme/js/__internal/core/speech_recognition_adapter.ts

@@ -10,7 +10,7 @@ type SpeechRecognition = SpeechRecognitionConfig & {
 interface SpeechRecognitionEvents {
   onResult: (event: Event) => void;
   onError: (event: Event) => void;
-  onEnd: () => void;
+  onEnd: (event: Event) => void;
 }
 
 export const NOT_SUPPORTED_ERROR = 'E1065';

packages/devextreme/js/__internal/ui/speech_to_text/speech_to_text.ts

@@ -27,14 +27,15 @@ enum SpeechToTextState {
   DISABLED = 'disabled',
 }
 
-type SpeechToTextActions = Pick<SpeechToTextProperties, 'onStartClick' | 'onStopClick' | 'onResult' | 'onError'>;
+type SpeechToTextActions = Pick<SpeechToTextProperties, 'onStartClick' | 'onStopClick' | 'onResult' | 'onError' | 'onEnd'>;
 type PointerLikeEvent = KeyboardEvent | MouseEvent | PointerEvent | TouchEvent;
 
 const ACTIONS: (keyof SpeechToTextActions)[] = [
   'onStartClick',
   'onStopClick',
   'onResult',
   'onError',
+  'onEnd',
 ];
 
 type Properties = SpeechToTextProperties & {
@@ -68,6 +69,8 @@ class SpeechToText extends Widget<Properties> {
       onStopClick: undefined,
       onResult: undefined,
       onError: undefined,
+      onEnd: undefined,
+      speechRecognitionConfig: undefined,
     };
   }
 
@@ -204,7 +207,7 @@ class SpeechToText extends Widget<Properties> {
       : startText ?? '';
   }
 
-  private _emitNativeEvent<K extends keyof Pick<SpeechToTextActions, 'onResult' | 'onError'>>(name: K, event: Event): void {
+  private _emitNativeEvent<K extends keyof Pick<SpeechToTextActions, 'onResult' | 'onError' | 'onEnd'>>(name: K, event: Event): void {
     this._actions[name]?.({ component: this, element: this.element(), event });
   }
 
@@ -244,10 +247,12 @@ class SpeechToText extends Widget<Properties> {
     this._emitDxEvent('onStopClick', e.event);
   }
 
-  private _handleSpeechRecognitionEnd(): void {
+  private _handleSpeechRecognitionEnd(event: Event): void {
     if (this._state !== SpeechToTextState.DISABLED && !this._isCustomSpeechRecognitionEnabled()) {
       this._setState(SpeechToTextState.INITIAL);
     }
+
+    this._emitNativeEvent('onEnd', event);
   }
 
   private _handleSpeechRecognitionResult(event: Event): void {
@@ -258,6 +263,12 @@ class SpeechToText extends Widget<Properties> {
     this._emitNativeEvent('onError', event);
   }
 
+  private _stopRecognitionOnDisable(disabled?: boolean): void {
+    if (disabled) {
+      this._speechRecognitionAdapter?.stop();
+    }
+  }
+
   private _setState(newState: SpeechToTextState): void {
     if (this._state === newState) {
       return;
@@ -315,6 +326,7 @@ class SpeechToText extends Widget<Properties> {
       case 'disabled':
         this._button?.option(name, value);
         this._setState(value ? SpeechToTextState.DISABLED : SpeechToTextState.INITIAL);
+        this._stopRecognitionOnDisable(value);
         break;
 
       case 'startIcon':

packages/devextreme/js/ui/speech_to_text.d.ts

@@ -98,6 +98,14 @@ export type ResultEvent = EventInfo<dxSpeechToText> & { event: Event };
  */
 export type ErrorEvent = EventInfo<dxSpeechToText> & { event: Event };
 
+/**
+ * @docid _ui_speech_to_text_EndEvent
+ * @public
+ * @type object
+ * @inherits EventInfo
+ */
+export type EndEvent = EventInfo<dxSpeechToText> & { event: Event };
+
 /**
  * @docid _ui_speech_to_text_ContentReadyEvent
  * @public
@@ -225,6 +233,15 @@ export interface Properties extends WidgetOptions<dxSpeechToText> {
    * @public
    */
   onError?: ((e: ErrorEvent) => void) | undefined;
+
+  /**
+   * @docid dxSpeechToTextOptions.onEnd
+   * @default undefined
+   * @type_function_param1 e:{ui/speech_to_text:EndEvent}
+   * @action
+   * @public
+   */
+  onEnd?: ((e: EndEvent) => void) | undefined;
 }
 
 /**
@@ -258,7 +275,7 @@ type FilterOutHidden<T> = Omit<T, 'onFocusIn' | 'onFocusOut'>;
 type EventsIntegrityCheckingHelper = CheckedEvents<
   FilterOutHidden<Properties>,
   Required<Events>,
-  'onStartClick' | 'onStopClick' | 'onResult' | 'onError'
+  'onStartClick' | 'onStopClick' | 'onResult' | 'onError' | 'onEnd'
 >;
 
 /**

packages/devextreme/js/ui/speech_to_text_types.d.ts

@@ -5,6 +5,7 @@ export {
   StopClickEvent,
   ResultEvent,
   ErrorEvent,
+  EndEvent,
   ContentReadyEvent,
   DisposingEvent,
   InitializedEvent,

packages/devextreme/testing/tests/DevExpress.ui.widgets/speechToText.tests.js

@@ -753,7 +753,7 @@ QUnit.module('Options', moduleConfig, () => {
 
 QUnit.module('Component Lifecycle', moduleConfig, () => {
     QUnit.test('should properly initialize actions with noop fallback', function(assert) {
-        const expectedActions = ['onStartClick', 'onStopClick', 'onResult', 'onError'];
+        const expectedActions = ['onStartClick', 'onStopClick', 'onResult', 'onError', 'onEnd'];
 
         expectedActions.forEach(action => {
             assert.notStrictEqual(this.instance._actions[action], undefined, `${action} action initialized`);
@@ -869,6 +869,7 @@ QUnit.module('SpeechRecognitionAdapter integration', moduleConfig, () => {
         const actionsSpies = {
             onResult: sinon.spy(),
             onError: sinon.spy(),
+            onEnd: sinon.spy(),
         };
 
         this.reinit(actionsSpies);
@@ -878,6 +879,7 @@ QUnit.module('SpeechRecognitionAdapter integration', moduleConfig, () => {
         const actions = [
             { option: 'onResult', method: 'onresult', spy: actionsSpies.onResult, event: { type: 'result' } },
             { option: 'onError', method: 'onerror', spy: actionsSpies.onError, event: { type: 'error' } },
+            { option: 'onEnd', method: 'onend', spy: actionsSpies.onEnd, event: { type: 'end' } },
         ];
 
         actions.forEach(({ option, method, spy, event }) => {
@@ -953,14 +955,16 @@ QUnit.module('SpeechRecognitionAdapter integration', moduleConfig, () => {
         assert.strictEqual(this.getSpeechRecognition().lang, 'fr-FR', 'config updated in recognition instance');
     });
 
-    QUnit.test('should update onResult/onError handlers at runtime', function(assert) {
+    QUnit.test('should update onResult/onError/onEnd handlers at runtime', function(assert) {
         const initialActionsSpies = {
             onResult: sinon.spy(),
             onError: sinon.spy(),
+            onEnd: sinon.spy(),
         };
         const updatedActionsSpies = {
             onResult: sinon.spy(),
             onError: sinon.spy(),
+            onEnd: sinon.spy(),
         };
 
         this.reinit(initialActionsSpies);
@@ -970,6 +974,8 @@ QUnit.module('SpeechRecognitionAdapter integration', moduleConfig, () => {
         const actions = [
             { prop: 'onresult', option: 'onResult', initial: initialActionsSpies.onResult, updated: updatedActionsSpies.onResult, event: { type: 'result' } },
             { prop: 'onerror', option: 'onError', initial: initialActionsSpies.onError, updated: updatedActionsSpies.onError, event: { type: 'error' } },
+            { prop: 'onend', option: 'onEnd', initial: initialActionsSpies.onEnd, updated: updatedActionsSpies.onEnd, event: { type: 'error' } },
+
         ];
 
         actions.forEach(({ prop, option, initial, updated, event }) => {
@@ -983,14 +989,15 @@ QUnit.module('SpeechRecognitionAdapter integration', moduleConfig, () => {
         });
     });
 
-    QUnit.test('should allow subscribing to result/error via .on()', function(assert) {
-        assert.expect(6);
+    QUnit.test('should allow subscribing to result/error/end via .on()', function(assert) {
+        assert.expect(9);
 
         this.reinit();
 
         const events = [
             { eventName: 'result', trigger: 'onresult' },
             { eventName: 'error', trigger: 'onerror' },
+            { eventName: 'end', trigger: 'onend' },
         ];
 
         const speechRecognition = this.getSpeechRecognition();
@@ -1006,6 +1013,20 @@ QUnit.module('SpeechRecognitionAdapter integration', moduleConfig, () => {
         });
     });
 
+    QUnit.test('should stop recognition when disabled set to true at runtime', function(assert) {
+        this.reinit();
+        const adapter = this.getAdapter();
+        const stopSpy = sinon.spy(adapter, 'stop');
+
+        this.getButton().trigger('dxclick');
+        assert.ok(this.$element.hasClass(SPEECH_TO_TEXT_LISTENING_CLASS), 'component in listening state');
+
+        this.instance.option('disabled', true);
+
+        assert.ok(stopSpy.calledOnce, 'stop called when disabled');
+        assert.ok(!this.$element.hasClass(SPEECH_TO_TEXT_LISTENING_CLASS), 'state reset after disabling');
+    });
+
     QUnit.test('should dispose adapter and set it to null', function(assert) {
         this.reinit();
 

packages/devextreme/ts/dx.all.d.ts

@@ -27762,6 +27762,13 @@ declare module DevExpress.ui {
      */
     export type DisposingEvent =
       DevExpress.common.core.events.EventInfo<dxSpeechToText>;
+    /**
+     * [descr:_ui_speech_to_text_EndEvent]
+     */
+    export type EndEvent =
+      DevExpress.common.core.events.EventInfo<dxSpeechToText> & {
+        event: Event;
+      };
     /**
      * [descr:_ui_speech_to_text_ErrorEvent]
      */
@@ -27856,6 +27863,11 @@ declare module DevExpress.ui {
        * [descr:dxSpeechToTextOptions.onError]
        */
       onError?: ((e: ErrorEvent) => void) | undefined;
+
+      /**
+       * [descr:dxSpeechToTextOptions.onEnd]
+       */
+      onEnd?: ((e: EndEvent) => void) | undefined;
     }
     /**
      * [descr:_ui_speech_to_text_ResultEvent]