1. Introduction

This document describes editing related additions to 2 events - Input and beforeinput which are described in the UI events spec [UI-EVENTS]. The goal of these events is to allow authors to understand and/or override default edit behavior both before and after editing occurs.

2. Definitions

DataTransfer

A DataTransfer object contains richtext and plaintext data for some inputtypes. [DATA-TRANSFER]

express intention

A user can express an intention to execute a specific editing operation by means of keyboard, IME, speech, or similar method. Specific input actions are mapped to intentions following platform-specific conventions.

kill buffer

This definition is not normative.

A kill buffer is a in-memory store of richtext content that is separate from the clipboard which allows for the temporal storage of content that was deleted using specific deletion commands. The user can replace the current selection with the content held in the kill buffer by indicating an intention to yank the kill buffer.

3. Problems solved

This section is not normative.

Creating a webbased texteditor requires a considerable amount of JavaScript on top of the browser code, among other things because:

1. Browsers do not handle all editing operations the same way.
2. Browsers are often buggy in the way they handle certain editing operations.
3. Individual sites may have custom preferences for how they want to handle certain editing operations.
4. The development of high-level text editing features in browsers has not followed the principles laid out in the Extensible Web Manifesto in that development of these features has not always been in coordination with the needs of the web developer community.

This spec seeks to alleviate the problem by providing a simple way for web developers to both override browser handling of all user input related to text editing through the beforeinput event, and to monitor what browsers have changed in the DOM due to user input trough the input event.

4. Use cases

This section is not normative.

1. Creating a JavaScript text editor in which the <strong>-tag is used instead of the <b>-tag to mark text that the user marks as bold, using any browser-builtin way to mark a text as bold, without having access to all existing browsers.
2. Creating a JavaScript text editor which works with a data model in the background where JavaScript takes care of rendering changes to the edited text to the DOM.
3. Creating a JavaScript editor which only allows a subset of richtext editing (for example: bold is allowed, but italic not).
4. Creating a collaborative editor in which JavaScript is used to render changes to the DOM, based on user intentions with users using different browsers with different ways of expressing specific intentions.
5. Creating a JavaScript editor with different user access options, where some users only can add or delete text and other users only can add or remove certain types of formatting.

5. Input Event Types

Input events are sent before (beforeinput event) and after (input event) a user attempts to edit the markup. This includes insertion and deletion of content, and formatting changes.

Input events are dispatched [ UI-EVENTS] on elements that act as editing hosts, including elements with the contenteditable attribute set, textarea elements, and input elements that permit text input.

partial interface InputEvent {
    readonly attribute DOMString     inputType;
    readonly attribute DataTransfer? dataTransfer;
    sequence<StaticRange> getTargetRanges();
};

partial dictionary InputEventInit {
    DOMString             inputType = "";
    DataTransfer?         dataTransfer = null;
    sequence<StaticRange> targetRanges = [];
};

6. Event order during IME composition

An IME composition causes several beforeinput events, not all of which can be canceled.

1. If the composition is starting with an empty initial composition string (i.e. the composition is not recomposing an existing range of the DOM), this step is skipped.

   1. The UA extracts the initial composition string from the DOM.
   2. A beforeinput event with the inputType "deleteByComposition" is dispatched [ UI-EVENTS].
   3. Unless the beforeinput event has been canceled, the initial composition string is removed from the DOM.
   4. Unless the beforeinput event has been canceled, an input event with the inputType "deleteByComposition" is dispatched [ UI-EVENTS].
   Note

   This note is not normative.

   The default action for this beforeinput event is the removal of the targetRanges from the DOM (i.e. the initial composition string will be removed from the DOM).

   The beforeinput event can be canceled. Canceling the event will prevent the browser from removing the initial composition string from the DOM. Canceling or handling the event will not prevent the composition from taking place or influence the contents of the initial composition string.

2. A compositionstart event is dispatched. [UI-EVENTS].

3. If the composition has an empty initial composition string, this step is skipped.

   1. A beforeinput event with the inputType "insertCompositionText" is dispatched [ UI-EVENTS] with the data attribute set to the initial composition string.
   2. The DOM is updated with the insertion of the initial composition string at the start of the selection.
   3. An input event with the inputType "insertCompositionText" is dispatched [UI-EVENTS]
   Note

   This note is not normative.

   Notice that the beforeinput event cannot be canceled.

4. With each DOM update of the composition string:

   1. A beforeinput event with the inputType "insertCompositionText" is dispatched [ UI-EVENTS] with the data attribute set to the updated contents of the composition text.
   2. A compositionupdate event is dispatched. [UI-EVENTS].
   3. The DOM is updated.
   4. An input event with the inputType "insertCompositionText" is dispatched [ UI-EVENTS].
   Note

   This step is repeated as long as no text is to be committed to the DOM (i.e. is made to be part of the DOM outside the range controlled by the composition).

5. When a part or the entire composition string is to be committed to the DOM:

   1. A beforeinput event with the inputType "deleteCompositionText" is dispatched [ UI-EVENTS].
   2. The contents of the range controlled by the composition process is removed from the DOM.
   3. A beforeinput event with the inputType "insertFromComposition" is dispatched [ UI-EVENTS] with the data attribute set to the part of the final composition string that is to be committed to the DOM.
   4. Unless the beforeinput event with the inputType "insertFromComposition" has been canceled, the DOM is updated with the part of the composition string that is to be committed to the DOM inserted at the start of the selection.
   5. A compositionend event is dispatched. [UI-EVENTS].
   6. Unless the beforeinput event with the inputType "insertFromComposition" has been canceled, a input event with the inputType "insertFromComposition" is dispatched

6. If only a part of the composition string was committed to the DOM, while another part is not yet to be committed, the process starts over from step 3 with the non-committed part of the final composition string as the new initial composition string.

7. Privacy and security considerations

This section is not normative.

There are no known security or privacy impacts of this feature beyond fingerprinting [ fingerprinting-guidance] techniques that already are available through existing events, such as the keydown and keypress [ UI-EVENTS] events.

If this feature replaces existing events, it MAY lead to a decline in available fingerprinting [ fingerprinting-guidance] techniques, as users' intentions are recorded, and not the particular type of hardware they used to express this intention.

8. Acknowledgements

Thanks to: Michael Aufreiter, Adrian Bateman, Oliver Buchtala, Robin Berjon, Enrica Casucci, Bo Cupp, Domenic Denicola, Emil Eklund, Olivier Forget, Aryeh Gregor, Marijn Haverbeke, Yoshifumi Inoue, Koji Ishii, Gary Kacmarcik, Ian Kilpatrick, Frederico Caldeira Knabben, Takayoshi Kochi, Piotrek Koszuliński, Travis Leithead, Grisha Lyukshin, Miles Maxfield, Chaals McCathie Nevile, Masayuki Nakano, Ryosuke Niwa, Julie Parent, Ben Peters, Florian Rivoal, Morgan Smith, Hallvord R. M. Steen, Johan Sörlin, Cristian Talau, Dave Tapuska, Ojan Vafai, Léonie Watson, Xiaoqian Wu, Chong Zhang, Joanmarie, and everyone in the Editing Taskforce for their input and feedback.