docs: edit event-binding doc copy and headers (#38903)

PR Close #38903

.pullapprove.yml

@@ -371,6 +371,7 @@ groups:
           'aio/content/guide/built-in-template-functions.md',
           'aio/content/examples/built-in-template-functions/**',
           'aio/content/guide/event-binding.md',
+          'aio/content/guide/event-binding-concepts.md',
           'aio/content/examples/event-binding/**',
           'aio/content/guide/interpolation.md',
           'aio/content/examples/interpolation/**',

aio/content/guide/event-binding-concepts.md

@@ -0,0 +1,31 @@
+
+# How event binding works
+
+In an event binding, Angular configures an event handler for the target event.
+You can use event binding with your own custom events.
+
+When the component or directive raises the event, the handler executes the template statement.
+The template statement performs an action in response to the event.
+
+## Handling events
+
+A common way to handle events is to pass the event object, `$event`, to the method handling the event.
+The `$event` object often contains information the method needs, such as a user's name or an image URL.
+
+The target event determines the shape of the `$event` object.
+If the target event is a native DOM element event, then `$event` is a [DOM event object](https://developer.mozilla.org/en-US/docs/Web/Events), with properties such as `target` and `target.value`.
+
+In the following example the code sets the `<input>` `value` property by binding to the `name` property.
+
+
+<code-example path="event-binding/src/app/app.component.html" region="event-binding-3" header="src/app/app.component.html"></code-example>
+
+With this example, the following actions occur:
+
+1. The code binds to the `input` event of the `<input>` element, which allows the code to listen for changes.
+1. When the user makes changes, the component raises the `input` event.
+1. The binding executes the statement within a context that includes the DOM event object, `$event`.
+1. Angular retrieves the changed text by following the path `$event.target.value` and updates the `name` property.
+
+If the event belongs to a directive or component, `$event` has the shape that the directive or component produces.
+

aio/content/guide/event-binding.md

@@ -1,7 +1,6 @@
-# Event binding `(event)`
+# Event binding
 
-Event binding allows you to listen for certain events such as
+Event binding allows you to listen for and respond to user actions such as keystrokes, mouse movements, clicks, and touches.
-keystrokes, mouse movements, clicks, and touches.
 
 <div class="alert is-helpful">
 
@@ -9,100 +8,59 @@ See the <live-example></live-example> for a working example containing the code
 
 </div>
 
-Angular event binding syntax consists of a **target event** name
+## Binding to events
-within parentheses on the left of an equal sign, and a quoted
+
-template statement on the right.
+To bind to an event you use the Angular event binding syntax.
-The following event binding listens for the button's click events, calling
+This syntax consists of a target event name within parentheses to the left of an equal sign, and a quoted template statement to the right.
-the component's `onSave()` method whenever a click occurs:
+In the following example, the target event name is `click` and the template statement is `onSave()`.
+
+<code-example language="html" header="Event binding syntax">
+&lt;button (click)="onSave()"&gt;Save&lt;button&gt;
+</code-example>
+
+The event binding listens for the button's click events and calls the component's `onSave()` method whenever a click occurs.
 
 <div class="lightbox">
   <img src='generated/images/guide/template-syntax/syntax-diagram.svg' alt="Syntax diagram">
 </div>
 
-## Target event
-
-As above, the target is the button's click event.
-
-<code-example path="event-binding/src/app/app.component.html" region="event-binding-1" header="src/app/app.component.html"></code-example>
-
-Alternatively, use the `on-` prefix, known as the canonical form:
-
-<code-example path="event-binding/src/app/app.component.html" region="event-binding-2" header="src/app/app.component.html"></code-example>
-
-Element events may be the more common targets, but Angular looks first to see if the name matches an event property
-of a known directive, as it does in the following example:
-
-<code-example path="event-binding/src/app/app.component.html" region="custom-directive" header="src/app/app.component.html"></code-example>
-
-If the name fails to match an element event or an output property of a known directive,
-Angular reports an “unknown directive” error.
-
-## *$event* and event handling statements
-
-In an event binding, Angular sets up an event handler for the target event.
-
-When the event is raised, the handler executes the template statement.
-The template statement typically involves a receiver, which performs an action
-in response to the event, such as storing a value from the HTML control
-into a model.
-
-The binding conveys information about the event. This information can include data values such as an event object, string, or number named `$event`.
-
-The target event determines the shape of the `$event` object.
-If the target event is a native DOM element event, then `$event` is a
-[DOM event object](https://developer.mozilla.org/en-US/docs/Web/Events),
-with properties such as `target` and `target.value`.
-
-Consider this example:
-
-<code-example path="event-binding/src/app/app.component.html" region="event-binding-3" header="src/app/app.component.html"></code-example>
-
-This code sets the `<input>` `value` property by binding to the `name` property.
-To listen for changes to the value, the code binds to the `input`
-event of the `<input>` element.
-When the user makes changes, the `input` event is raised, and the binding executes
-the statement within a context that includes the DOM event object, `$event`.
-
-To update the `name` property, the changed text is retrieved by following the path `$event.target.value`.
-
-If the event belongs to a directive&mdash;recall that components
-are directives&mdash;`$event` has whatever shape the directive produces.
-
 ## Custom events with `EventEmitter`
 
-Directives typically raise custom events with an Angular [EventEmitter](api/core/EventEmitter).
+[Directives](guide/built-in-directives) typically raise custom events with an Angular [EventEmitter](api/core/EventEmitter) as follows.
-The directive creates an `EventEmitter` and exposes it as a property.
+
-The directive calls `EventEmitter.emit(payload)` to fire an event, passing in a message payload, which can be anything.
+1. The directive creates an `EventEmitter` and exposes it as a property.
-Parent directives listen for the event by binding to this property and accessing the payload through the `$event` object.
+1. The directive then calls `EventEmitter.emit(data)` to emit an event, passing in message data, which can be anything.
+1. Parent directives listen for the event by binding to this property and accessing the data through the `$event` object.
 
 Consider an `ItemDetailComponent` that presents item information and responds to user actions.
-Although the `ItemDetailComponent` has a delete button, it doesn't know how to delete the hero. It can only raise an event reporting the user's delete request.
+Although the `ItemDetailComponent` has a delete button, it doesn't contain the functionality to delete the hero.
+It can only raise an event reporting the user's delete request.
 
-Here are the pertinent excerpts from that `ItemDetailComponent`:
 
 <code-example path="event-binding/src/app/item-detail/item-detail.component.html" header="src/app/item-detail/item-detail.component.html (template)" region="line-through"></code-example>
 
+The component defines a `deleteRequest` property that returns an `EventEmitter`.
+When the user clicks **Delete**, the component invokes the `delete()` method, telling the `EventEmitter` to emit an `Item` object.
+
 <code-example path="event-binding/src/app/item-detail/item-detail.component.ts" header="src/app/item-detail/item-detail.component.ts (deleteRequest)" region="deleteRequest"></code-example>
 
-The component defines a `deleteRequest` property that returns an `EventEmitter`.
+The hosting parent component binds to the `deleteRequest` event of the `ItemDetailComponent` as follows.
-When the user clicks *delete*, the component invokes the `delete()` method,
-telling the `EventEmitter` to emit an `Item` object.
-
-Now imagine a hosting parent component that binds to the `deleteRequest` event
-of the `ItemDetailComponent`.
 
 <code-example path="event-binding/src/app/app.component.html" header="src/app/app.component.html (event-binding-to-component)" region="event-binding-to-component"></code-example>
 
-When the `deleteRequest` event fires, Angular calls the parent component's
+When the `deleteRequest` event fires, Angular calls the parent component's `deleteItem()` method with the item.
-`deleteItem()` method, passing the *item-to-delete* (emitted by `ItemDetail`)
-in the `$event` variable.
 
-## Template statements have side effects
+### Determining an event target
 
-Though [template expressions](guide/interpolation#template-expressions) shouldn't have [side effects](guide/property-binding-best-practices#avoid-side-effects), template
+To determine an event target, Angular checks if the name of the target event matches an event property of a known directive.
-statements usually do. The `deleteItem()` method does have
+In the following example, Angular checks to see if `myClick` is an event on the custom `ClickDirective`.
-a side effect: it deletes an item.
 
-Deleting an item updates the model, and depending on your code, triggers
+<code-example path="event-binding/src/app/app.component.html" region="custom-directive" header="src/app/app.component.html"></code-example>
-other changes including queries and saving to a remote server.
+
-These changes propagate through the system and ultimately display in this and other views.
+If the target event name, `myClick` fails to match an element event or an output property of `ClickDirective`, Angular reports an "unknown directive" error.
+
+<hr />
+
+## What's next
+
+For more information on how event binding works, see [How event binding works](guide/event-binding-concepts).

aio/content/navigation.json

@@ -777,6 +777,11 @@
                   "url": "guide/architecture-next-steps",
                   "title": "Next Steps",
                   "tooltip": "Beyond the basics."
+                },
+                {
+                  "url": "guide/event-binding-concepts",
+                  "title": "How event binding works",
+                  "tooltip": "About event binding."
                 }
               ]
             },