[Common UI] Initial commonUI bundles

Bring in work on general-purpose and over-arching
user interface bundles from the sandbox transition
branch. WTD-574.

platform/commonUI/edit/src/objects/EditableDomainObject.js

@@ -0,0 +1,84 @@
+/*global define*/
+
+/**
+ * Defines EditableDomainObject, which wraps domain objects
+ * such that user code may work with and mutate a copy of the
+ * domain object model; these changes may then be propagated
+ * up to the real domain object (or not) by way of invoking
+ * save or cancel behaviors of the "editor.completion"
+ * capability (a capability intended as internal to edit
+ * mode; invoked by way of the Save and Cancel actions.)
+ */
+define(
+    [
+        '../capabilities/EditablePersistenceCapability',
+        '../capabilities/EditableContextCapability',
+        '../capabilities/EditorCapability',
+        './EditableDomainObjectCache'
+    ],
+    function (
+        EditablePersistenceCapability,
+        EditableContextCapability,
+        EditorCapability,
+        EditableDomainObjectCache
+    ) {
+        "use strict";
+
+        var capabilityFactories = {
+            persistence: EditablePersistenceCapability,
+            context: EditableContextCapability,
+            composition: EditableContextCapability,
+            editor: EditorCapability
+        };
+
+        // Handle special case where "editor.completion" wraps persistence
+        // (other capability overrides wrap capabilities of the same type.)
+        function getDelegateArguments(name, args) {
+            return name === "editor" ? ['persistence'] : args;
+        }
+
+        /**
+         * An EditableDomainObject overrides capabilities
+         * which need to behave differently in edit mode,
+         * and provides a "working copy" of the object's
+         * model to allow changes to be easily cancelled.
+         */
+        function EditableDomainObject(domainObject) {
+            // The cache will hold all domain objects reached from
+            // the initial EditableDomainObject; this ensures that
+            // different versions of the same editable domain object
+            // are not shown in different sections of the same Edit
+            // UI, which might thereby fall out of sync.
+            var cache;
+
+            // Constructor for EditableDomainObject, which adheres
+            // to the same shared cache.
+            function EditableDomainObjectImpl(domainObject) {
+                var model = JSON.parse(JSON.stringify(domainObject.getModel())),
+                    editableObject = Object.create(domainObject);
+
+                // Only provide the cloned model.
+                editableObject.getModel = function () { return model; };
+
+                // Override certain capabilities
+                editableObject.getCapability = function (name) {
+                    var delegateArguments = getDelegateArguments(name, arguments),
+                        capability = domainObject.getCapability.apply(this, delegateArguments),
+                        factory = capabilityFactories[name];
+
+                    return (factory && capability) ?
+                            factory(capability, editableObject, domainObject, cache) :
+                            capability;
+                };
+
+                return editableObject;
+            }
+
+            cache = new EditableDomainObjectCache(EditableDomainObjectImpl);
+
+            return cache.getEditableObject(domainObject);
+        }
+
+        return EditableDomainObject;
+    }
+);

platform/commonUI/edit/src/objects/EditableDomainObjectCache.js

@@ -0,0 +1,102 @@
+/*global define*/
+
+
+/**
+ * An editable domain object cache stores domain objects that have been
+ * made editable, in a group that can be saved all-at-once. This supports
+ * Edit mode, which is launched for a specific object but may contain
+ * changes across many objects.
+ *
+ * Editable domain objects have certain specific capabilities overridden
+ * to ensure that changes made while in edit mode do not propagate up
+ * to the objects used in browse mode (or to persistence) until the user
+ * initiates a Save.
+ *
+ * @module editor/object/editable-domain-object-cache
+ */
+define(
+    function () {
+        'use strict';
+
+        /**
+         * Construct a new cache for editable domain objects. This can be used
+         * to get-or-create editable objects, particularly to support wrapping
+         * of objects retrieved via composition or context capabilities as
+         * editable domain objects.
+         *
+         * @param {Constructor<EditableDomainObject>} EditableDomainObject a
+         *        constructor function which takes a regular domain object as
+         *        an argument, and returns an editable domain object as its
+         *        result.
+         * @constructor
+         * @memberof module:editor/object/editable-domain-object-cache
+         */
+        function EditableDomainObjectCache(EditableDomainObject) {
+            var cache = {},
+                dirty = {};
+
+            return {
+                /**
+                 * Wrap this domain object in an editable form, or pull such
+                 * an object from the cache if one already exists.
+                 *
+                 * @param {DomainObject} domainObject the regular domain object
+                 * @returns {DomainObject} the domain object in an editable form
+                 */
+                getEditableObject: function (domainObject) {
+                    var id = domainObject.getId();
+                    return (cache[id] =
+                        cache[id] || new EditableDomainObject(domainObject));
+                },
+                /**
+                 * Mark an editable domain object (presumably already cached)
+                 * as having received modifications during editing; it should be
+                 * included in the bulk save invoked when editing completes.
+                 *
+                 * @param {DomainObject} domainObject the domain object
+                 */
+                markDirty: function (domainObject) {
+                    dirty[domainObject.getId()] = domainObject;
+                },
+                /**
+                 * Mark an object (presumably already cached) as having had its
+                 * changes saved (and thus no longer needing to be subject to a
+                 * save operation.)
+                 *
+                 * @param {DomainObject} domainObject the domain object
+                 */
+                markClean: function (domainObject) {
+                    delete dirty[domainObject.getId()];
+                },
+                /**
+                 * Initiate a save on all objects that have been cached.
+                 */
+                saveAll: function () {
+                    var object;
+
+                    // Most save logic is handled by the "editor.completion"
+                    // capability, but this in turn will typically invoke
+                    // Save All. An infinite loop is avoided by marking
+                    // objects as clean as we go.
+
+                    function doSave(editCapability) {
+                        return editCapability.save();
+                    }
+
+                    while (Object.keys(dirty).length > 0) {
+                        // Pick the first dirty object
+                        object = dirty[Object.keys(dirty)[0]];
+
+                        // Mark non-dirty to avoid successive invocations
+                        this.markClean(object);
+
+                        // Invoke its save behavior
+                        object.getCapability('editor.completion').then(doSave);
+                    }
+                }
+            };
+        }
+
+        return EditableDomainObjectCache;
+    }
+);