Update events documentation #139
Conversation
Note, adds TODOs in sections where specific refinement is in progress.
|
A live preview of this PR will be available at the URL(s) below. https://pr139-70fca6c---lit-dev-bvxw3ycs6q-uw.a.run.app/ |
|
|
||
| ## Where to add your event listeners | ||
| ## Listening to events |
There was a problem hiding this comment.
This intro section talking about addEventListener seems unnecessary, since it's not the primary way to add events, and putting it up front makes it seem that way.
I would just add the MDN link to the "Adding event listeners to the component or its shadow root" section below:
To be notified of an event dispatched from the component's slotted children as well as children rendered into shadow DOM via the component template, you can add a listener to the component itself using the standard
addEventListenerDOM method (See EventTarget.addEventListener() on MDN for full details on this API).
There was a problem hiding this comment.
I was suggesting removing this discussion altogether (since it's primarily about how to imperatively call addEventListener to nodes, which is not the primary way to add events in Lit, and putting this section up front makes it feel that way.
Since the only time you should have to call addEventListener imperatively today is when adding listeners to the shadow root or host, and you already have a section on that, I'd removed this preamble and go directly into "Adding event listeners in the element template".
|
|
||
| If your component adds an event listener to anything except itself or its children–for example, to `Window`, `Document`, or some element in the main DOM–you should add the listener in `connectedCallback` and remove it in `disconnectedCallback`. | ||
| See [Working with events in shadow DOM](#shadowdom) for more information. |
There was a problem hiding this comment.
Suggest removing newline between paragraphs, since this cross-reference is related to the previous paragraph.
|
|
||
| Whether or not an event bubbles depends on the value of its `bubbles` property. To check if a particular event bubbles: | ||
| To make a custom event pass through shadow DOM boundaries, you must set both the `composed` and `bubbles` flags to `true`: |
There was a problem hiding this comment.
This is not exactly correct, the options are distinct. IOW composed: true events can either bubble or not. If not bubbling, they will just re-target on every shadow host up the tree, just not bubble through each node in the composed tree. afaiu.
|
|
||
| To make a custom event pass through shadow DOM boundaries, you must set both the `composed` and `bubbles` flags to `true`: | ||
| For example, the `preventDefault()` method can be called to indicate the event's standard action should not occur. For example, calling `preventDefault()` in a listener for the click event of a checkbox prevents the checkbox from becoming checked when clicked. |
There was a problem hiding this comment.
Consecutive use of "For example"
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
|
|
||
| ## Where to add your event listeners | ||
| ## Listening to events |
There was a problem hiding this comment.
I was suggesting removing this discussion altogether (since it's primarily about how to imperatively call addEventListener to nodes, which is not the primary way to add events in Lit, and putting this section up front makes it feel that way.
Since the only time you should have to call addEventListener imperatively today is when adding listeners to the shadow root or host, and you already have a section on that, I'd removed this preamble and go directly into "Adding event listeners in the element template".
| @@ -300,7 +289,7 @@ See the [MDN documentation on composedPath](https://developer.mozilla.org/en-US/ | |||
|
|
|||
| Events exist primarily to communicate changes from the event dispatcher to the event listener, but events can also be used to communicate information from the listener back to the dispatcher. | |||
There was a problem hiding this comment.
The title of this section and its contents don't really connect for me. Based on the title, I expected it to focus on a listener setting data on to the event that the dispatcher then retrieves synchronously after dispatch, but it talks mostly about preventDefault, which sorta feels random, and skims over the details of actual communication between dispatcher and listener. 🤷
Co-authored-by: Kevin Schaaf <kschaaf@google.com>
Fixes #66, #67, #68, #69.
@aomarks Just need a quick review of the change to litdev-example.