Skip to content

Clarify when details should go on events vs targets #585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Clarify when details should go on events vs targets #585

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0985dde
Clarify when details should go on events vs targets
jakearchibald Sep 17, 2025
9337eb6
Update index.bs
jakearchibald Sep 17, 2025
1193cfa
Provide counter-example
jakearchibald Sep 17, 2025
4c962eb
Tweaks
jakearchibald Sep 17, 2025
209d533
Grammar tweaks
jakearchibald Sep 17, 2025
0d037b5
Tweaks
jakearchibald Sep 17, 2025
0c3916f
Apply suggestions from code review
jakearchibald Sep 18, 2025
726b82f
Remove counter-example
jakearchibald Sep 18, 2025
c3ab2f1
Merge branch 'main' into clarify-event-subclassing
jakearchibald Sep 18, 2025
3459c82
Document exception case
jakearchibald Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1615,7 +1615,7 @@ Unlike dictionaries, interfaces:
(i.e., one can check if it is an `instanceof` a particular class on the global scope),

Defining an interface also exposes it on the global scope, allowing for the specification of static methods.
For example, the `canParse()` static method of the URL interface.
For example, the `canParse()` static method of the URL interface.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated change, but it's something many editors do automatically. I can remove it, but I imagine others will run into the same thing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are not the only one. We should maybe lint for trailing whitespace.


```JS
if (URL.canParse(someURL)) {
Expand Down Expand Up @@ -2554,12 +2554,30 @@ as it implies that it's possible to dispatch an event asynchronously.
All events are dispatched synchronously.
What is more often implied by "asynchronous event" is to defer firing an event.

<h3 id="state-and-subclassing">Use plain {{Event}}s for state</h3>
<h3 id="state-and-subclassing">Put state on {{Event/target}} objects rather than {{Event}}s</h3>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous heading seemed… incomplete.


Where possible, use a plain {{Event}} with a specified `type`,
and capture any state information in the {{Event/target}} object.
Where possible, capture any state information in the {{Event/target}} object,
and use events with a specified `type` to signal updates to that state.

It's usually not necessary to create new subclasses of {{Event}}.
<div class="note">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this need to be a note?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did it to separate the rule from the explanation of the rule, since the explanation is non-normative. But this spec doesn't have such a strict divide between normative and non-normative. But I don't mind either way, happy to go with whatever you think.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if I understand this paragraph...

Or if it's completely accurate. There are a few events that are fired asynchronously, e.g. slotchange. The state on the event target might have been updated when the event listener is triggered.

This means the {{Event/target}} object can used to determine the current state,
without waiting for the next \'change\' event.

This is particularly useful if there's a final state,
where there will be no further \'change\' events.
</div>

It's usually not necessary to create new subclasses of {{Event}},
but they can be used to provide information relating to how the state change occurred.

<div class="example">
Properties on {{HTMLInputElement}},
such as {{HTMLInputElement/value}},
provide the state of the input.
Properties on {{InputEvent}},
such as {{InputEvent/inputType}},
describe the nature of an update to the state.
</div>

<h3 id="events-vs-observers">Use Events and Observers appropriately</h3>

Expand Down