5144 rename throttle component changed (#5151)

* rename  throttleComponentChanged -> throttleLeadingAndTrailing

* document throttleLeadingAndTrailing

* @dmarcos says we don't need to preserve 1.3.0 interface

* No need to define this MD variable twice.

Author: diarmidmackenzie

docs/core/utils.md

@@ -212,6 +212,20 @@ AFRAME.registerComponent('foo', {
 });
 ```
 
+### `AFRAME.utils.throttleLeadingAndTrailing (function, minimumInterval [, optionalContext])`
+
+Returns a throttled function that is called at most once every `minimumInterval` milliseconds, but ensures that the very last call of a burst gets deferred until the end of the interval.  This is useful when an event is used to trigger synchronization of state, and there is a need to converge to the correct final state following a burst of events.
+
+Example use cases:
+
+ * synchronizing state based on the componentchanged event
+ * following a mouse pointer using the mousemove event
+ * integrating with [THREE.TransformControls](https://threejs.org/docs/#examples/en/controls/TransformControls), via the objectChange event.
+
+A context such as `this` can be provided to handle function binding for convenience. 
+
+The same as [lodash's`throttle`][lodash], with `leading` and `trailing` options both set to `true`
+
 ## Miscellaneous
 
 ### `AFRAME.utils.getUrlParameter (name)`

src/core/component.js

@@ -72,7 +72,10 @@ var Component = module.exports.Component = function (el, attrValue, id) {
   }
 
   // Last value passed to updateProperties.
-  this.throttledEmitComponentChanged = utils.throttleComponentChanged(function emitChange () {
+  // This type of throttle ensures that when a burst of changes occurs, the final change to the
+  // component always triggers an event (so a consumer of this event will end up reading the correct
+  // final state, following a burst of changes).
+  this.throttledEmitComponentChanged = utils.throttleLeadingAndTrailing(function emitChange () {
     el.emit('componentchanged', self.evtDetail, false);
   }, 200);
   this.updateProperties(attrValue);

src/utils/index.js

@@ -68,14 +68,21 @@ module.exports.throttle = function (functionToThrottle, minimumInterval, optiona
  * Returns throttle function that gets called at most once every interval.
  * If there are multiple calls in the last interval we call the function one additional
  * time.
- * It behaves like a throttle except for the very last call that gets deferred until the end of the interval.
+ * It behaves like throttle except for the very last call that gets deferred until the end of the interval.
+ * This is useful when an event is used to trigger synchronization of state, and there is a need to converge
+ * to the correct final state following a burst of events.
+ *
+ * Example use cases:
+ * - synchronizing state based on the componentchanged event
+ * - following a mouse pointer using the mousemove event
+ * - integrating with THREE.TransformControls, via the objectChange event.
  *
  * @param {function} functionToThrottle
  * @param {number} minimumInterval - Minimal interval between calls (milliseconds).
  * @param {object} optionalContext - If given, bind function to throttle to this context.
  * @returns {function} Throttled function.
  */
-module.exports.throttleComponentChanged = function (functionToThrottle, minimumInterval, optionalContext) {
+module.exports.throttleLeadingAndTrailing = function (functionToThrottle, minimumInterval, optionalContext) {
   var lastTime;
   var deferTimer;
   if (optionalContext) {