Form submit event (#11989)

* feat(forms): ngSubmit event exposes $event from original submit event as local variable

Modify NgForm directive and FormGroup directive to expose the original submit event as $event in the ngSubmit event. Modify docs to reflect changes.

This resolves #10920.

* refactor: code cleanup

modules/@angular/forms/test/reactive_integration_spec.ts

@@ -529,17 +529,17 @@ export function main() {
     });
 
     describe('submit and reset events', () => {
-      it('should emit ngSubmit event on submit', () => {
+      it('should emit ngSubmit event with the original submit event on submit', () => {
         const fixture = TestBed.createComponent(FormGroupComp);
         fixture.componentInstance.form = new FormGroup({'login': new FormControl('loginValue')});
-        fixture.componentInstance.data = 'should be changed';
+        fixture.componentInstance.event = null;
         fixture.detectChanges();
 
         const formEl = fixture.debugElement.query(By.css('form')).nativeElement;
         dispatchEvent(formEl, 'submit');
 
         fixture.detectChanges();
-        expect(fixture.componentInstance.data).toEqual('submitted');
+        expect(fixture.componentInstance.event.type).toEqual('submit');
       });
 
       it('should mark formGroup as submitted on submit event', () => {
@@ -1760,7 +1760,7 @@ class FormControlComp {
 @Component({
   selector: 'form-group-comp',
   template: `
-    <form [formGroup]="form" (ngSubmit)="data='submitted'">
+    <form [formGroup]="form" (ngSubmit)="event=$event">
       <input type="text" formControlName="login">
     </form>
   `
@@ -1769,7 +1769,7 @@ class FormGroupComp {
   control: FormControl;
   form: FormGroup;
   myGroup: FormGroup;
-  data: string;
+  event: Event;
 }
 
 @Component({

modules/@angular/forms/test/template_integration_spec.ts

@@ -237,15 +237,15 @@ export function main() {
     });
 
     describe('submit and reset events', () => {
-      it('should emit ngSubmit event on submit', fakeAsync(() => {
+      it('should emit ngSubmit event with the original submit event on submit', fakeAsync(() => {
            const fixture = TestBed.createComponent(NgModelForm);
-           fixture.componentInstance.name = 'old';
+           fixture.componentInstance.event = null;
 
            const form = fixture.debugElement.query(By.css('form'));
            dispatchEvent(form.nativeElement, 'submit');
            tick();
 
-           expect(fixture.componentInstance.name).toEqual('submitted');
+           expect(fixture.componentInstance.event.type).toEqual('submit');
          }));
 
       it('should mark NgForm as submitted on submit event', fakeAsync(() => {
@@ -898,13 +898,14 @@ class StandaloneNgModel {
 @Component({
   selector: 'ng-model-form',
   template: `
-    <form (ngSubmit)="name='submitted'" (reset)="onReset()">
+    <form (ngSubmit)="event=$event" (reset)="onReset()">
       <input name="name" [(ngModel)]="name" minlength="10" [ngModelOptions]="options">
     </form>
   `
 })
 class NgModelForm {
   name: string;
+  event: Event;
   options = {};
 
   onReset() {}