UndoManager and DOM Transaction

Status

This document is an early proposal of the specification for Undo Manager and DOM transaction. This specification will replace the UndoManager section of the main HTML specification.

Table of Contents

1. 1 Introduction
2. 2 Undo Scope and Undo Manager
   1. 2.1 Definitions
   2. 2.2 Scoping Undo Transaction History
      1. 2.2.1 Undo scope and contenteditable
      2. 2.2.2 undoScope IDL attribute
   3. 2.3 The UndoManager interface
      1. 2.3.1 undoManager IDL attribute
   4. 2.4 Undo: moving forward in the undo transaction history
   5. 2.5 Redo: moving backward in the undo transaction history
3. 3 DOM Transaction and DOM changes
   1. 3.1 Mutations of DOM
      1. 3.1.1 Reverting DOM changes
      2. 3.1.2 Reapplying DOM changes
   2. 3.2 The DOMTransaction interface
   3. 3.3 Automatic DOM transactions
      1. 3.3.1 Automatic transactions and manual DOM changes
   4. 3.4 Manual DOM transactions
4. 4 Transaction, Undo, and Redo Events
   1. 4.1 The DOMTransactionEvent interface

1 Introduction

This specification defines the API to manage user agent's undo transaction history (also known as undo stack) and make objects that can be managed by the undo transaction history.

Many rich text editors on the Web add editing operations that are not natively supported by execCommand and other Web APIs. For example, many editors make modifications to DOM after an user agent executed user editing actions to work-around user agent bugs and to customize for their use.

However, doing so breaks user agent's native undo and redo because the user agent cannot undo DOM modifications made by scripts. This forces the editors to re-implement undo and redo entirely from scratch, and many editors, indeed, store innerHTML as string and recreate the entire editable region whenever a user tires to undo and redo. This is very inefficient and has limited the depth of their undo stack.

Also, any Web app that tries to mix contenteditable region or text fields with canvas or other non-text editable regions will have to reimplement undo and redo of contenteditable regions as well because the user agent typically has one undo transaction history per document, and there is no easy way to add new undo entry to the user agent's native undo transaction history.

This specification tries to address above issues by providing ways to define undo scopes, add items to user agent's native undo transaction history, and create a sequence of DOM changes that can be automatically undone or redone by user agents.

2 Undo Scope and Undo Manager

2.1 Definitions

The user agent must associate an undo transaction history, a list of sequences of DOM transactions, with each UndoManager object.

The undo transaction history has an undo position. This is the position between two entries in the undo transaction history's list where the next entry represents what needs to happen when undo is done, and the previous entry represents what needs to happen when redo is done.

The undo scope is the collection of DOM nodes that are managed by the same UndoManager. A document node or an element with undoscope attribute that is either an editing host or not editable defines a new undo scope, and all descendent nodes of the element, excluding elements with and descendent nodes of elements with undoscope attribute, will be managed by a new UndoManager. An undo scope host is a document, or an element with undoscope attribute that is either an editing host or not editable.

2.2 Scoping Undo Transaction History

The undoscope attribute is a boolean attribute that controls the default undo scope of an element. It is to separate undo transaction histories of multiple editable regions without scripts. Using undoscope content attribute, authors can easily set text fields in a widget to have a separate undo transaction histories for example.

When the undoscope content attribute is added to an editing host or an element that is not editable, the user agent must define new undo scope for the element, and create a new UndoManager to manage any DOM changes made to all descendent nodes of the element excluding undo scope hosts and their descendents.

When the undoscope content attribute is removed from an editing host or an element that is not editable, the user agent must remove all entries in the undo transaction history of the corresponding undo scope without unapplying or reapplying them and disconnect the corresponding UndoManager for the scope. After the removal, the node from which the content attribute is removed and their descendent nodes, excluding undo scope hosts and their descendents, belong to the undo scope of the closest ancestor with the undoscope content attribute or of the document.

2.2.1 Undo scope and contenteditable

contenteditable content attribute does not define a new undo scope and all editing hosts share the same UndoManager by default. And the undoscope content attribute on an editable element is ignored except on editing hosts.

When the contenteditable content attribute is set to true on an element, the user agent must disconnect the UndoManagers of all descendent undo scope hosts of the element that have become editable due to the change as if the undoscope content attribute was removed from those nodes.

Conversely, when the contenteditable content attribute is removed from an element or set to false, the user agent must behave as if undoscope content attribute is removed and added back to all descendent nodes of the element that have become non-editable due to the change.

<div id="container">
    <div undoscope>This will be editable</div>
    <div contenteditable="false" undoscope>This will remain not editable.</div>
</div>
<script>
var container = document.getElementById('container');
var children = container.getElementsByTagName('*');
children[0].undoManager.transact({executeAutomatic: function () {}});
children[1].undoManager.transact({executeAutomatic: function () {}});
container.contentEditable = true;
alert(children[0].undoManager); // Alerts null
alert(children[1].undoManager.length); // Alerts 1
</script>

2.2.2 undoScope IDL attribute

partial interface Element {
    attribute boolean undoScope;
};

element . undoScope

Returns true if the element is an undo scope host and false otherwise.

2.3 The UndoManager interface

To manage transaction entries in the undo transaction history, the UndoManager interface can be used:

interface UndoManager {
    void transact(in DOMTransaction transaction, in boolean merge);
    void undo();
    void redo();
    getter DOMTransaction[] item(in unsigned long index);
    readonly attribute unsigned long length;
    readonly attribute unsigned long position;
    void clearUndo();
    void clearRedo();
};

document . undoManager

Returns the UndoManager object.

element . undoManager

Returns the UndoManager object.

undoManager . transact(transaction, merge)

Clears entries above the current undo position, applies transaction, and adds it to the beginning of the first entry in undo transaction history, or of a new undo transaction history if merge is set to false.

undoManager . undo()

Unapplies all DOM transactions in the entry immediately after the current position in the reverse order and increments position by 1 if position < length.

undoManager . redo()

Reapplies all DOM transactions in the entry immediately before the current position and decrements position by 1 if position > 0

undoManager . position

Returns the number of the current entry in the undo transaction history. (Entries at and past this point are redo entries.)

undoManager . length

Returns the number of entries in the undo transaction history.

data = undoManager . item(index)

undoManager[index]

Returns the entry with index index in the undo transaction history.

Returns null if index is out of range.

undoManager . clearUndo()

Removes entries in the undo transaction history before position and resets position to 0.

undoManager . clearRedo()

Removes entries in the undo transaction history after position.

Each entry in the UndoManager consists of one or more DOM transactions, all of which are unapplied and reapplied togehter in one undo or redo.

document.undoManager.transact(...);
document.undoManager.transact(..., true);
document.undoManager.transact(..., true);
alert(document.undoManager.item(0).length); // Alerts 3
document.undoManager.item(0).pop();
alert(document.undoManager.item(0).length); // Still alerts 3
alert(document.undoManager.item(0) === document.undoManager.item(0)); // Alerts false

A typical use case for having multiple DOM transactions in one entry is for typing multiple letters, spaces, and new lines that must be undone or redone in one step.

// Assume myEditor is some element that has undoscope attribute, and insert(node) is a function that inserts the specified node at where the caret is.
myEditor.undoManager.transact({executeAutomatic: function () {
    insert(document.createTextNode('o')); }, label: 'Typing'});
myEditor.undoManager.transact({executeAutomatic: function () {
    insert(document.createTextNode('k')); }, label: 'Typing'}, true);
myEditor.undoManager.transact({executeAutomatic: function () {
    insert(document.createElement('br')); }, label: 'Typing'});
myEditor.undoManager.transact({executeAutomatic: function () {
    insert(document.createTextNode('hi')); }, label: 'Typing'}), true);

Because Mac OS X and other frameworks expect applications to provide an array of undo items, simply dispatching undo and redo events and having scripts manage undo transaction history would not let the user agent populate the native UI properly.

2.3.1 undoManager IDL attribute

partial interface Element {
    attribute UndoManager undoManager;
};

element . undoManager

Returns the UndoManager object associated with the element's undo scope if the element is an undo scope host, or null otherwise.

partial interface Document {
    attribute UndoManager undoManager;
};

document . undoManager

Returns the UndoManager object associated with the document.

2.4 Undo: moving forward in the undo transaction history

When the user invokes an undo operation, or when the execCommand() method is called with the undo command, the user agent must perform an undo operation on the active undo manager by calling the undo() method.

2.5 Redo: moving backward in the undo transaction history

When the user invokes a redo operation, or when the execCommand() method is called with the redo command, the user agent must perform an redo operation on the active undo manager by calling the redo() method.

3 DOM Transaction and DOM changes

A DOM transaction is an ordered set of DOM changes associated with a unique undo scope host that can be applied, unapplied, or reapplied.

To apply a DOM transaction means to make the associated DOM changes under the associated undo scope host. And to unapply and to reapply a DOM transaction means, respectively, to revert and to remake the associated DOM changes under the associated undo scope host.

A DOM transaction can be unapplied or reapplied if it appears, respectively, immediately after or immediately before the undo position in the associated UndoManager's undo transaction history.

3.1 Mutations of DOM

DOM changes of a node is a sequence s₁, s₂, ... s_n where each s_i with 1 ≤ i ≤ n is either one of:

• Inserting or removing a node under the element.
• Replacement of character data.
• Appending, removing, or changing a content attribute of the element or descendent nodes of the element.
• Setting textarea element's value IDL attribute or input elment's value IDL attribute.

The DOM state of a node is the state of all descendent nodes and their attributes that are affected by DOM changes of the element. If two DOM states of a node are equal, then the node and all its descendent nodes must be identical.

3.1.1 Reverting DOM changes

To revert DOM changes of the sequence s₁, s₂, ... s_n, revert each s_i with 1 ≤ i ≤ n in the reverse order s_n, s_n-1, ... s₁ as specified below:

To revert inserting a node into a parent before a child, run these steps:

1. If node is not null and its parent is not parent, then terminate these steps.
2. If child is not null and its parent is not parent, then terminate these steps.
3. If child is not null and its previous sibling is not node, then terminate these steps.
4. Pre-remove node from parent.

To revert removing a node from a parent, let child be the next sibling of node before the removal, and run these steps:

1. If node is not null and its parent is not null, then terminate these steps.
2. If child is not null and its parent is not parent, then terminate these steps.
3. Pre-insert child into parent before child.

To revert replacing data of a node with an offset, count, and data, let replacedData be the substringed data with node, offset, and count before the replacement, and run these steps:

1. If node's length attribute is less than offset, terminate these steps.
2. Replace data of node with offset, the length of data, and replacedData.

To revert changing an attribute whose namespace is namespace and local name is localName to value, let oldValue be the content attribute value before the change, oldPrefix be the namespace prefix before the change, and change the attribute to oldValue and set the namespace prefix to oldPrefix.

To revert appending an attribute whose namespace is namespace and local name is localName to a node and setting the namespace prefix to prefix, run these steps.

1. If a content attribute whose namespace is namespace and local name is localName doesn't exist on the node, then terminate these steps.
2. Otherwise, remove the attribute whose namespace is namespace and local name is localName.

To revert removing an attribute whose namespace is namespace and local name is localName from a node, let oldValue be the content attribute value and oldPrefix be the namespace prefix both before the removal, and run these steps.

1. If a content attribute whose namespace is namespace and local name is localName exists on the node, then terminate these steps.
2. Otherwise, create and append the attribute whose namespace is namespace and local name is localName, with oldValue as the content attribute value and set the namespace prefix to oldPrefix.

To revert setting textarea element's value IDL attribute and input element's value IDL attribute to value, set element's value IDL attribute to the raw value of the textarea element and the value of the input element before the setting respectively.

3.1.2 Reapplying DOM changes

To reapply DOM changes of the sequence s₁, s₂, ... s_n, reapply each s_i with 1 ≤ i ≤ n in the same order s₁, s₂, ... s_n as specified below:

To reapply inserting a node into a parent before a child, run these steps:

1. If node is not null and its parent is not null, then terminate these steps.
2. If child is not null and its parent is not parent, then terminate these steps.
3. Pre-insert child into parent before child.

To reapply removing a node from a parent, let child be the next sibling of node before the removal, and run these steps:

1. If node is not null and its parent is not parent, then terminate these steps.
2. If child is not null and its parent is not parent, then terminate these steps.
3. If child is not null and its previous sibling is not node, then terminate these steps.
4. Pre-remove node from parent.

To reapply replacing data of a node with an offset, count, and data, and run these steps:

1. If node's length attribute is less than offset, terminate these steps.
2. Replace data of node with offset, count, and replacedData.

To reapply changing an attribute whose namespace is namespace and local name is localName to value, let prefix be the namespace prefix after the change, and change the attribute to value and set the namespace prefix to prefix.

To reapply appending an attribute whose namespace is namespace and local name is localName with value as the content attribute value to a node and setting the namespace prefix to prefix, run these steps:

1. If a content attribute whose namespace is namespace and local name is localName exists on the node, then terminate these steps.
2. Otherwise, append the attribute whose namespace is namespace and local name is localName with value as the content attribute value to the node, and set namespace prefix to prefix.

To reapply removing an attribute whose namespace is namespace and local name is localName from a node, run these steps.

1. If a content attribute whose namespace is namespace and local name is localName doesn't exist on the node, then terminate these steps.
2. Otherwise, remove the attribute whose namespace is namespace and local name is localName.

To reapply setting textarea element's value IDL attribute or input elment's value IDL attribute to value, set element's value IDL attribute to value.

3.2 The DOMTransaction interface

[NoInterfaceObject]
interface DOMTransaction {
    attribute DOMString label;
    attribute Function? executeAutomatic;
    attribute Function? execute;
    attribute Function? undo;
    attribute Function? redo;
};

document.undoManager.transact({ execute: function () {
    this.execute = function () { alert('foo'); }
    alert('bar');
}, undo: function () { alert('baz'); } }); // alerts 'bar'
document.undoManager.item(0)[0].undo = function() { alert('foobar'); }
docuemnt.undoManager.undo(); // alerts 'foobar'

var scope = document.createElement('div');
scope.undoScope = true;
document.body.appendChild(scope);
scope.undoManager.transact({executeAutomatic: function () {
    scope.appendChild("foo");
    alert(scope.textContent); // "foo"
    scope.undoScope = false;
}});
scope.undoManager.undo(); // Throws an error because undoManager returns null.

3.3 Automatic DOM transactions

An automatic DOM transaction is a DOM transaction where DOM changes are tracked by the user agent and the logic to unapply or reapply the transaction is implicitly created by the user agent.

var scope = document.createElement('div');
scope.undoScope = true;
document.body.appendChild(scope);
scope.undoManager.transact({executeAutomatic: function () {
    document.body.appendChild("foo");
    scope.appendChild("bar");
}});
scope.undoManager.undo();
alert(document.body.textContent); // Alerts "foo".

In an automatic DOM transaction, execute attribute is ignored.

3.3.1 Automatic transactions and manual DOM changes

Authors should not modify nodes that are used by automatic DOM transactions in reverting or reapplying DOM changes as it will interfere with the user agent's attempt to unapply or reapply automatic DOM transactions.

var b = document.createTextNode("b");
b.appendChild(document.createTextNode("hello"));
document.body.appendChild(b);
document.undoManager.transact({ executeAutomatic: function () {
    document.body.appendChild(document.createTextNode(" world")); }});
b.appendChild(document.body.lastChild);
document.undoManager.undo(); // No-op.

document.undoManager.redo(); // No-op.
document.body.appendChild(b.lastChild);
document.undoManager.undo(); // " world" is removed from document.body

3.4 Manual DOM transactions

A manual DOM transaction is a DOM transaction where the logic to apply, unapply, or reapply the transaction is explicitly defined by an application. It provides a way to communicate with user agent's undo transaction history, e.g. to populate user agent's undo menu.

In a manual DOM transaction, executeAutomatic attribute is ignored.

Manual DOM transactions may be incompatible with automatic DOM transactions, in particular, with user editing actions if manual DOM transaction mutates nodes that are dependent on by automatic DOM transactions.

function drawLine(start, end, style) {
    document.undoManager.transact({ execute: function () {
            // Draw a line on canvas
        }, undo: function () {
            // Undraw a line
        }, redo: function () { this.execute(); },
        'Draw a line'
    });
}

4 Transaction, Undo, and Redo Events

When a new DOM transaction is applied by transact() method to an undo transaction history of a UndoManager, the user agent must fire a DOM transaction event using the TransactionEvent interface. When a DOM transaction is unapplied or reapplied though undo() method or redo() method, of a UndoManager, the user agent must fire an undo event and a redo event respectively.

4.1 The DOMTransactionEvent interface

[Constructor(DOMString type, optional EventInit eventInitDict)]
interface DOMTransactionEvent : Event {
    readonly attribute Object transaction;
};

DOMTransactionEvent . transaction

Returns the transaction object that triggered this event.