fix(forms): make composition event buffering configurable (#15256)

This commit fixes a regression where `ngModel` no longer syncs
letter by letter on Android devices, and instead syncs at the
end of every word. This broke when we introduced buffering of
IME events so IMEs like Pinyin keyboards or Katakana keyboards
wouldn't display composition strings. Unfortunately, iOS devices
and Android devices have opposite event behavior. Whereas iOS
devices fire composition events for IME keyboards only, Android
fires composition events for Latin-language keyboards. For
this reason, languages like English don't work as expected on
Android if we always buffer. So to support both platforms,
composition string buffering will only be turned on by default
for non-Android devices.

However, we have also added a `COMPOSITION_BUFFER_MODE` token
to make this configurable by the application. In some cases, apps
might might still want to receive intermediate values. For example,
some inputs begin searching based on Latin letters before a
character selection is made.

As a provider, this is fairly flexible. If you want to turn
composition buffering off, simply provide the token at the top
level:

```ts
providers: [
   {provide: COMPOSITION_BUFFER_MODE, useValue: false}
]
```

Or, if you want to change the mode  based on locale or platform,
you can use a factory:

```ts
import {shouldUseBuffering} from 'my/lib';

....
providers: [
   {provide: COMPOSITION_BUFFER_MODE, useFactory: shouldUseBuffering}
]
```

Closes #15079.

PR Close #15256

packages/forms/src/directives/default_value_accessor.ts

@@ -6,8 +6,8 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Directive, ElementRef, Renderer, forwardRef} from '@angular/core';
-
+import {Directive, ElementRef, Inject, InjectionToken, Optional, Renderer, forwardRef} from '@angular/core';
+import {ɵgetDOM as getDOM} from '@angular/platform-browser';
 import {ControlValueAccessor, NG_VALUE_ACCESSOR} from './control_value_accessor';
 
 export const DEFAULT_VALUE_ACCESSOR: any = {
@@ -16,6 +16,21 @@ export const DEFAULT_VALUE_ACCESSOR: any = {
   multi: true
 };
 
+/**
+ * We must check whether the agent is Android because composition events
+ * behave differently between iOS and Android.
+ */
+function _isAndroid(): boolean {
+  const userAgent = getDOM() ? getDOM().getUserAgent() : '';
+  return /android (\d+)/.test(userAgent.toLowerCase());
+}
+
+/**
+ * Turn this mode on if you want form directives to buffer IME input until compositionend
+ * @experimental
+ */
+export const COMPOSITION_BUFFER_MODE = new InjectionToken<boolean>('CompositionEventMode');
+
 /**
  * The default accessor for writing a value and listening to changes that is used by the
  * {@link NgModel}, {@link FormControlDirective}, and {@link FormControlName} directives.
@@ -32,15 +47,29 @@ export const DEFAULT_VALUE_ACCESSOR: any = {
       'input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]',
   // TODO: vsavkin replace the above selector with the one below it once
   // https://github.com/angular/angular/issues/3011 is implemented
-  // selector: '[ngControl],[ngModel],[ngFormControl]',
-  host: {'(input)': 'onChange($event.target.value)', '(blur)': 'onTouched()'},
+  // selector: '[ngModel],[formControl],[formControlName]',
+  host: {
+    '(input)': '_handleInput($event.target.value)',
+    '(blur)': 'onTouched()',
+    '(compositionstart)': '_compositionStart()',
+    '(compositionend)': '_compositionEnd($event.target.value)'
+  },
   providers: [DEFAULT_VALUE_ACCESSOR]
 })
 export class DefaultValueAccessor implements ControlValueAccessor {
   onChange = (_: any) => {};
   onTouched = () => {};
 
-  constructor(private _renderer: Renderer, private _elementRef: ElementRef) {}
+  /** Whether the user is creating a composition string (IME events). */
+  private _composing = false;
+
+  constructor(
+      private _renderer: Renderer, private _elementRef: ElementRef,
+      @Optional() @Inject(COMPOSITION_BUFFER_MODE) private _compositionMode: boolean) {
+    if (this._compositionMode == null) {
+      this._compositionMode = !_isAndroid();
+    }
+  }
 
   writeValue(value: any): void {
     const normalizedValue = value == null ? '' : value;
@@ -53,4 +82,17 @@ export class DefaultValueAccessor implements ControlValueAccessor {
   setDisabledState(isDisabled: boolean): void {
     this._renderer.setElementProperty(this._elementRef.nativeElement, 'disabled', isDisabled);
   }
+
+  _handleInput(value: any): void {
+    if (!this._compositionMode || (this._compositionMode && !this._composing)) {
+      this.onChange(value);
+    }
+  }
+
+  _compositionStart(): void { this._composing = true; }
+
+  _compositionEnd(value: any): void {
+    this._composing = false;
+    this._compositionMode && this.onChange(value);
+  }
 }

packages/forms/src/directives/ng_model.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Directive, EventEmitter, Host, HostListener, Inject, Input, OnChanges, OnDestroy, Optional, Output, Self, SimpleChanges, forwardRef} from '@angular/core';
+import {Directive, EventEmitter, Host, Inject, Input, OnChanges, OnDestroy, Optional, Output, Self, SimpleChanges, forwardRef} from '@angular/core';
 
 import {FormControl} from '../model';
 import {NG_ASYNC_VALIDATORS, NG_VALIDATORS} from '../validators';
@@ -114,7 +114,6 @@ export class NgModel extends NgControl implements OnChanges,
   _control = new FormControl();
   /** @internal */
   _registered = false;
-  private _composing = false;
   viewModel: any;
 
   @Input() name: string;
@@ -124,15 +123,6 @@ export class NgModel extends NgControl implements OnChanges,
 
   @Output('ngModelChange') update = new EventEmitter();
 
-  @HostListener('compositionstart')
-  compositionStart(): void { this._composing = true; }
-
-  @HostListener('compositionend')
-  compositionEnd(): void {
-    this._composing = false;
-    this.update.emit(this.viewModel);
-  }
-
   constructor(@Optional() @Host() parent: ControlContainer,
               @Optional() @Self() @Inject(NG_VALIDATORS) validators: Array<Validator|ValidatorFn>,
               @Optional() @Self() @Inject(NG_ASYNC_VALIDATORS) asyncValidators: Array<AsyncValidator|AsyncValidatorFn>,
@@ -176,7 +166,7 @@ export class NgModel extends NgControl implements OnChanges,
 
               viewToModelUpdate(newValue: any): void {
                 this.viewModel = newValue;
-                !this._composing && this.update.emit(newValue);
+                this.update.emit(newValue);
               }
 
               private _setUpControl(): void {

packages/forms/src/forms.ts

@@ -23,7 +23,7 @@ export {AbstractFormGroupDirective} from './directives/abstract_form_group_direc
 export {CheckboxControlValueAccessor} from './directives/checkbox_value_accessor';
 export {ControlContainer} from './directives/control_container';
 export {ControlValueAccessor, NG_VALUE_ACCESSOR} from './directives/control_value_accessor';
-export {DefaultValueAccessor} from './directives/default_value_accessor';
+export {COMPOSITION_BUFFER_MODE, DefaultValueAccessor} from './directives/default_value_accessor';
 export {Form} from './directives/form_interface';
 export {NgControl} from './directives/ng_control';
 export {NgControlStatus, NgControlStatusGroup} from './directives/ng_control_status';