Eliminate 2nd argument, add OptionalMutableData mixin/behavior.

lib/elements/dom-bind.html

@@ -15,7 +15,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
   (function() {
 
-    const domBindBase = Polymer.MutableData(Polymer.PropertyEffects(HTMLElement), true);
+    const domBindBase = Polymer.OptionalMutableData(Polymer.PropertyEffects(HTMLElement));
 
     /**
      * Custom element to allow using Polymer's template features (data binding,

lib/elements/dom-repeat.html

@@ -112,7 +112,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * @summary Custom element for stamping instance of a template bound to
    *   items in an array.
    */
-  class DomRepeat extends Polymer.MutableData(Polymer.Element, true) {
+  class DomRepeat extends Polymer.OptionalMutableData(Polymer.Element) {
 
     // Not needed to find template; can be removed once the analyzer
     // can find the tag name from customElements.define call

lib/legacy/mutable-data-behavior.html

@@ -13,7 +13,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 <script>
 (function() {
 
-  let mutablePropertyChange = Polymer.MutableData.mutablePropertyChange;
+  let mutablePropertyChange = Polymer.MutableData._mutablePropertyChange;
 
   /**
    * Legacy element behavior to skip strict dirty-checking for objects and arrays,
@@ -30,6 +30,66 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * bound to the same object graph.
    *
    * In cases where neither immutable patterns nor the data mutation API can be
+   * used, applying this mixin will cause Polymer to skip dirty checking for
+   * objects and arrays (always consider them to be "dirty").  This allows a
+   * user to make a deep modification to a bound object graph, and then either
+   * simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
+   * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
+   * elements that wish to be updated based on deep mutations must apply this
+   * mixin or otherwise skip strict dirty checking for objects/arrays.
+   *
+   * In order to make the dirty check strategy configurable, see
+   * `Polymer.OptionalMutableData`.
+   *
+   * Note, the performance characteristics of propagating large object graphs
+   * will be worse as opposed to using strict dirty checking with immutable
+   * patterns or Polymer's path notification API.
+   *
+   * @polymerBehavior
+   * @memberof Polymer
+   * @summary Behavior to skip strict dirty-checking for objects and
+   *   arrays
+   */
+  Polymer.MutableDataBehavior = {
+
+    /**
+     * Overrides `Polymer.PropertyEffects` to provide option for skipping
+     * strict equality checking for Objects and Arrays.
+     *
+     * This method pulls the value to dirty check against from the `__dataTemp`
+     * cache (rather than the normal `__data` cache) for Objects.  Since the temp
+     * cache is cleared at the end of a turn, this implementation allows
+     * side-effects of deep object changes to be processed by re-setting the
+     * same object (using the temp cache as an in-turn backstop to prevent
+     * cycles due to 2-way notification).
+     *
+     * @param {string} property Property name
+     * @param {*} value New property value
+     * @param {*} old Previous property value
+     * @return {boolean} Whether the property should be considered a change
+     * @protected
+     */
+    _shouldPropertyChange(property, value, old) {
+      return mutablePropertyChange(this, property, value, old, true);
+    }
+  };
+
+  /**
+   * Legacy element behavior to add the optional ability to skip strict
+   * dirty-checking for objects and arrays (always consider them to be
+   * "dirty") by setting a `mutable-data` attribute on an element instance.
+   *
+   * By default, `Polymer.PropertyEffects` performs strict dirty checking on
+   * objects, which means that any deep modifications to an object or array will
+   * not be propagated unless "immutable" data patterns are used (i.e. all object
+   * references from the root to the mutation were changed).
+   *
+   * Polymer also provides a proprietary data mutation and path notification API
+   * (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient
+   * mutation and notification of deep changes in an object graph to all elements
+   * bound to the same object graph.
+   *
+   * In cases where neither immutable patterns nor the data mutation API can be
    * used, applying this mixin will allow Polymer to skip dirty checking for
    * objects and arrays (always consider them to be "dirty").  This allows a
    * user to make a deep modification to a bound object graph, and then either
@@ -38,11 +98,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * elements that wish to be updated based on deep mutations must apply this
    * mixin or otherwise skip strict dirty checking for objects/arrays.
    *
-   * In cases where the intent is to allow the element user to determine the
-   * dirty checking strategy, define a default value for `mutableData` to `false`
-   * in the element's `properties` metadata, and the user can apply the
-   * `mutable-data` attribute (or set the `mutableData` property) to skip
-   * Object/Array dirty checking.
+   * While this behavior adds the ability to forgo Object/Array dirty checking,
+   * the `mutableData` flag defaults to false and must be set on the instance.
    *
    * Note, the performance characteristics of propagating large object graphs
    * will be worse by relying on `mutableData: true` as opposed to using
@@ -54,7 +111,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * @summary Behavior to skip strict dirty-checking for objects and
    *   arrays
    */
-  Polymer.MutableDataBehavior = {
+  Polymer.OptionalMutableDataBehavior = {
 
     properties: {
       /**
@@ -62,10 +119,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
        * for this element.  When true, Objects and Arrays will skip dirty
        * checking, otherwise strict equality checking will be used.
        */
-      mutableData: {
-        type: Boolean,
-        value: true
-      }
+      mutableData: Boolean
     },
 
     /**

lib/mixins/mutable-data.html

@@ -32,9 +32,73 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
   }
 
   /**
-   * Element class mixin to add the ability to skip strict dirty-checking for
-   * objects and arrays (always consider them to be "dirty"), for use on
-   * elements utilizing `Polymer.PropertyEffects`
+   * Element class mixin to skip strict dirty-checking for objects and arrays
+   * (always consider them to be "dirty"), for use on elements utilizing
+   * `Polymer.PropertyEffects`
+   *
+   * By default, `Polymer.PropertyEffects` performs strict dirty checking on
+   * objects, which means that any deep modifications to an object or array will
+   * not be propagated unless "immutable" data patterns are used (i.e. all object
+   * references from the root to the mutation were changed).
+   *
+   * Polymer also provides a proprietary data mutation and path notification API
+   * (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient
+   * mutation and notification of deep changes in an object graph to all elements
+   * bound to the same object graph.
+   *
+   * In cases where neither immutable patterns nor the data mutation API can be
+   * used, applying this mixin will cause Polymer to skip dirty checking for
+   * objects and arrays (always consider them to be "dirty").  This allows a
+   * user to make a deep modification to a bound object graph, and then either
+   * simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
+   * (e.g. `this.notifyPath('items')`) to update the tree.  Note that all
+   * elements that wish to be updated based on deep mutations must apply this
+   * mixin or otherwise skip strict dirty checking for objects/arrays.
+   *
+   * In order to make the dirty check strategy configurable, see
+   * `Polymer.OptionalMutableData`.
+   *
+   * Note, the performance characteristics of propagating large object graphs
+   * will be worse as opposed to using strict dirty checking with immutable
+   * patterns or Polymer's path notification API.
+   *
+   * @polymerMixin
+   * @memberof Polymer
+   * @summary Element class mixin to optionally skip strict dirty-checking
+   *   for objects and arrays
+   */
+  Polymer.MutableData = (superClass) => {
+
+    return class MutableData extends superClass {
+      /**
+       * Overrides `Polymer.PropertyEffects` to provide option for skipping
+       * strict equality checking for Objects and Arrays.
+       *
+       * This method pulls the value to dirty check against from the `__dataTemp`
+       * cache (rather than the normal `__data` cache) for Objects.  Since the temp
+       * cache is cleared at the end of a turn, this implementation allows
+       * side-effects of deep object changes to be processed by re-setting the
+       * same object (using the temp cache as an in-turn backstop to prevent
+       * cycles due to 2-way notification).
+       *
+       * @param {string} property Property name
+       * @param {*} value New property value
+       * @param {*} old Previous property value
+       * @return {boolean} Whether the property should be considered a change
+       * @protected
+       */
+      _shouldPropertyChange(property, value, old) {
+        return mutablePropertyChange(this, property, value, old, true);
+      }
+
+    }
+
+  };
+
+  /**
+   * Element class mixin to add the optional ability to skip strict
+   * dirty-checking for objects and arrays (always consider them to be
+   * "dirty") by setting a `mutable-data` attribute on an element instance.
    *
    * By default, `Polymer.PropertyEffects` performs strict dirty checking on
    * objects, which means that any deep modifications to an object or array will
@@ -55,12 +119,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * elements that wish to be updated based on deep mutations must apply this
    * mixin or otherwise skip strict dirty checking for objects/arrays.
    *
-   * The second `strictByDefault` argument to the mixin determines whether
-   * the element defaults to strict dirty checking or not. In cases where
-   * the intent is to allow the element user to determine the dirty checking
-   * strategy, set this argument to `true` and the element user can apply the
-   * `mutable-data` attribute (or set the `mutableData` property) to skip
-   * Object/Array dirty checking.
+   * While this mixin adds the ability to forgo Object/Array dirty checking,
+   * the `mutableData` flag defaults to false and must be set on the instance.
    *
    * Note, the performance characteristics of propagating large object graphs
    * will be worse by relying on `mutableData: true` as opposed to using
@@ -72,9 +132,9 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
    * @summary Element class mixin to optionally skip strict dirty-checking
    *   for objects and arrays
    */
-  Polymer.MutableData = (superClass, strictByDefault) => {
+  Polymer.OptionalMutableData = (superClass) => {
 
-    class MutableData extends superClass {
+    return class OptionalMutableData extends superClass {
 
       static get properties() {
         return {
@@ -82,12 +142,8 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
            * Instance-level flag for configuring the dirty-checking strategy
            * for this element.  When true, Objects and Arrays will skip dirty
            * checking, otherwise strict equality checking will be used.
-           * The default is determined at the point of mixin application.
            */
-          mutableData: {
-            type: Boolean,
-            value: !strictByDefault
-          }
+          mutableData: Boolean
         };
       }
 
@@ -114,15 +170,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     }
 
-    // For application directly to `Polymer.PropertyEffects` clients that
-    // don't use property defaults
-    MutableData.prototype.mutableData = !strictByDefault;
-
-    return MutableData;
   };
 
   // Export for use by legacy behavior
-  Polymer.MutableData.mutablePropertyChange = mutablePropertyChange;
+  Polymer.MutableData._mutablePropertyChange = mutablePropertyChange;
 
 })();
 </script>