Consider splitting the spec into smaller specifications

[garykac]

To make managing the UI Events specification a bit easier, and to facilitate the transition to a more algorithmic format for the spec, we're considering splitting the spec into a set of smaller (and more manageable) specifications.

This is also an opportunity to remove sections that should not be present in the spec, usually because they cover topics already (and more properly) defined elsewhere.

As such, I've done a "test split" of the spec to give people an idea of how it would look so that we can agree that this is a reasonable path forward. Note that this split was done with a slightly out-of-date version (December 2023) of the spec as a test just to see how it would look. If we agree to move forward with this, then the split will need to be re-done after we pause edits and flush the queue of pending pull requests.

As a high-level summary, we're considering splitting the monolithic UI Events spec into:

• UI Events (core)
  • Define the core UIEvent
• Composition
  • Could be merged with Keyboard, but probably best to keep separate.
• Focus
  • Can we remove this and rely entirely on the HTML spec? (https://html.spec.whatwg.org/#focus)
• Input
  • Define core "input" event functionality. Discuss with the editing group about possibly merging this with the editing work (which describes a lot of specific input event stuff). But this would occur after the split so that we can ensure the correct hooks are in place.
• Keyboard
• Mouse
  • Need to coordinate with PointerEvents spec
• Wheel

Some of these specs are currently small, but I imagine that they will grow once we start adding proper algorithms to the documents.

Proposal for each section:

• Abstract - Needs to be updated to be specific to each spec once they're split.
• Status of this document - boilerplate
• 1 Introduction
  • 1.1 Overview - needs update
  • 1.2 Conformance - boilerplate
• 2 Stylistic Conventions - mostly standard, with extra info mostly for key events
• 3 DOM Event Architecture - delete, except as noted below
  • 3.1 Event dispatch and DOM event flow - delete, this is defined elsewhere
  • 3.2 Default actions and cancelable events - delete, "default actions" should be part of the algo
  • 3.3 Synchronous and asynchronous events - delete, the algo for each event will define this
  • 3.4 Trusted events - verify that this is defined elsewhere
  • 3.5 Activation triggers and behavior - delete, covered by the algo for each event
  • 3.6 Constructing Mouse and Keyboard Events - move into Mouse and Keyboard specs
• 4 Basic Event Interfaces - first section is defined elsewhere and can be removed
  • 4.1 List of Event Types - Not needed, but maybe it's useful to have a list of all the events in the split specs?
• 5 Event Types
  • 5.1 User Interface Events
    • Keep UIEvent definition in core UIEvent spec
    • Should load, unload, abort, error, select be removed? Are they defined elsewhere?
  • 5.2 Focus Events - move to Focus Events spec
  • 5.3 Mouse Events - move to Mouse Events spec
  • 5.4 Wheel Events - move to Wheel Events spec
  • 5.5 Input Events - move to Input Events spec
  • 5.6 Keyboard Events - move to Keyboard Events spec
  • 5.7 Composition Events - move to Composition Events spec
• 6 Keyboard events and key values - move to Keyboard Events spec
• 7 Legacy Event Initializers - re-evaluate if any of these can be removed
  • 7.1 Legacy Event Initializer Interfaces
  • 7.1.1 Initializers for interface UIEvent - keep in core UIEvent spec
  • 7.1.2 Initializers for interface MouseEvent - move to Mouse Events spec
  • 7.1.3 Initializers for interface KeyboardEvent - move to Keyboard Events spec
  • 7.1.4 Initializers for interface CompositionEvent - move to Composition Events spec
• 8 Legacy Key & Mouse Event Attributes - re-evaluate if any of these can be removed
  • 8.1 Legacy UIEvent supplemental interface - keep in core, or delete?
  • 8.2 Legacy KeyboardEvent supplemental interface - move to Keyboard Event spec, or delete?
  • 8.3 Legacy key models - move to Keyboard Event spec, or delete?
• 9 Legacy Event Types
  • 9.1 Legacy UIEvent events - DOMActivate: move to core UI Event spec, or delete?
  • 9.2 Legacy FocusEvent events - DOMFocusIn, DOMFocusOut: move to Focus spec, or delete?
  • 9.3 Legacy KeyboardEvent events - move to Keyboard Event spec as deprecated
  • 9.4 Legacy MutationEvent events - move to UI core, or delete?:
    • DOMAttrModified, DOMCharacterDataModified, DOMNodeInserted, DOMNodeInsertedIntoDocument, DOMNodeRemoved, DOMNodeRemovedFromDocument, DOMSubtreeModified
• 10 Extending Events - non-normative, keep in UIEvents core, move somewhere else or remove?
  • 10.1 Introduction
  • 10.2 Custom Events
  • 10.3 Implementation-Specific Extensions
• 11 Security Considerations - adjust for each new spec
• 12 Changes - remove this section
  • 12.1 Changes between DOM Level 2 Events and UI Events
  • 12.2 Changes between different drafts of UI Events
• 13 Acknowledgements - dup into each spec? not sure how we would split this up.
• 14 Glossary - delete. most of these terms are defined properly elsewhere, and if they need to be defined in this spec then they should be defined inline
• Conformance et al - all boilerplate or auto-generated

[LJWatson]

Thanks @garykac. I haven't explored your experimental split in detail, but I think this plan makes a lot of sense.

With my Chair hat firmly on, do you think this will help us get some/all of the UI Events specs to Rec?

CC @patrickhlauke WRT the PE spec.

[patrickhlauke]

Regarding Pointer Events, we've got a few situations where we link back to (and, in some cases, expand/backfill the definitions provided in) the current monolithic UI Events spec. Purely from an organisational point of view, it always felt a bit odd that Pointer Events (and Touch Events) are split off and specific already, while the more "legacy"/entrenched inputs like keyboard and mouse are in the one monolithic spec - so purely on a gut feeling, I'd be inclined to agree that splitting these into more specific sub-specs makes sense

[smaug----]

I wonder if focus events are actually defined well enough, or almost well enough in the HTML spec.
https://html.spec.whatwg.org/#focus

[garykac]

@LJWatson : Considering the state of the specs and the amount of work needed, I believe that we won't be able to get UI Events to REC unless we split it up. Splitting out Keyboard code and key values into separate documents is the only reason why we were able to move those forward. We also need to convert the spec to be algorithmic, and that will be much easier if we can attack the problem piecemeal.

@patrickhlauke : One of the motivations for the monolithic spec was that there were interdependencies and event timing concerns that were easier to manage in a single document. PE (correctly, IMO) decided it was better to be a separate spec because they wanted to be able to actually finish the work without being anchored to all the other bits in UIEvents. Of course, that leads to interdependencies between the specs. Splitting up UI Events will cause more of these hooks/links between the specs, but it's a problem that needed to be solved in any case.

@smaug---- : I think that would be good outcome. And if the HTML spec is not sufficient, then it might make sense to update it rather than create a new FocusEvents spec.

[garykac]

The split files are as follows:

• UI Events (core)
• Composition Events
• Focus Events
• Input Events - (not to be confused with Input Events Level 2)
• Keyboard Events
• Mouse Events
• Wheel Events

Again, these are based on an out-of-date spec so please review the overall structure of the split and whether or not something belongs in one place or another (or not at all). The spec will be re-split once we agree on the general approach.

[zcorpan]

Have you considered moving UI Events to the WHATWG?

[annevk]

Once we add algorithms, wouldn't there be a lot of interdependencies? I worry this might end up being a nightmare to maintain.

I agree that focus can move fully into HTML though: #185.

[domenic]

Although I appreciate the from-scratch survey of existing sections and the desire to trim redundancies, I don't think creating separate documents is actually helpful. It just makes maintenance and looking things up harder, in my experience. Indeed, if anything, I'd like to see fewer documents, with much of UI Events moving into HTML.

[domenic]

Also, as always, I want to reiterate that reaching REC should be an anti-goal. Fundamental parts of the platform like this need to stay as living specs; we can't ever assume they're finished, and consign them to dead specs (RECs). If part of the motivation for the split here is process-related, I'd suggest setting that aside and instead focusing on the technically-best outcome. (Which, IMO, is somewhere between a merger with HTML and a monolithic UI Events spec. But, it's ultimately the editor's judgement, not mine.)

[marcoscaceres]

Right, putting aside the REC stuff (which I agree is an anti-goal once in CR), we should be seeing how much we can reduce this spec by deferring to DOM and HTML where possible.

The goal is maintainability though. There are just different means of getting there.

[garykac]

I think the most important goal is to migrate the spec to use properly written algorithms. That will be a significant aid to maintainability because the existing spec text (written mostly as "do something like this") has proven over the past decade or so to be far too vague to support the level of detail that we need. Regardless of where the spec ends up being hosted, this conversion needs to take place.

I wrote up some algorithms as a starting point a few years ago, and recently people have begun augmenting them because it allowed them to specify the details that they wanted. However, I know that the algorithms are inadequate and I also know that we have some browser implementation differences that will be tricky to specify correctly.

These inadequacies are why I've hesitated to propose incorporating the algorithms as they currently are into the main spec. The algorithms look more official than ad-hoc text descriptions, so errors feel more consequential.

Thus, my plan was to split the spec to remove the cruft and choose one event type (perhaps MouseEvents) as a canary to test migrating the algorithms over. That experience would inform how we move over the other events. We can't avoid having some interdependencies (e.g., PointerEvents), but I don't think the problem is unmanageable (referencing a different spec vs. referencing a distant section in the same spec).

If we don't split the spec into parts, then we need to have a plan for how to migrate to algorithms.

What do people think about the following approach:

• Remove sections that don't fit the modern specification structure: "DOM Event Architecture", "Changes", "Glossary"
• Choose one event (like MouseEvent) and update the main spec with the algorithms from the event-algo.bs file.
  • Iterate on the algorithms until they're "good enough" and then remove the old text.
• Rinse. Repeat.

Once (if) we have general agreement on the high-level approach, I'll create tracking issues for each task so it can be discussed in more detail. But I'm open to any suggestions.

[domenic]

What do people think about the following approach:

Sounds great!