Clean up and document event propagation properties (#5880)

* Add sourceTarget and propagatedFrom to events

Also documents events' target, sourceTarget, propagatedFrom
and layer properties.

Fixes #4510.

* Use propagatedFrom, which is equivalent of the original code

* propagetedFrom -> propagatedFrom

spec/suites/core/EventsSpec.js

@@ -565,6 +565,37 @@ describe('Events', function () {
 			expect(spy1.callCount).to.eql(0);
 			expect(spy2.callCount).to.eql(1);
 		});
+
+		it('sets target, sourceTarget and layer correctly', function () {
+			var obj = new L.Evented(),
+			    parent = new L.Evented(),
+			    spy1 = sinon.spy(),
+			    spy2 = sinon.spy();
+
+			/* register without context */
+			obj.on('test2', spy1);
+			parent.on('test2', spy2);
+
+			obj.addEventParent(parent);
+
+			/* Should be called once */
+			obj.fire('test2', null, true);
+
+			expect(spy1.calledWith({
+				type: 'test2',
+				target: obj,
+				sourceTarget: obj
+			})).to.be.ok();
+			expect(spy2.calledWith({
+				type: 'test2',
+				target: parent,
+				// layer should be deprecated in the future
+				// in favor of sourceTarget
+				layer: obj,
+				sourceTarget: obj,
+				propagatedFrom: obj
+			})).to.be.ok();
+		});
 	});
 
 	describe('#listens', function () {

spec/suites/layer/FeatureGroupSpec.js

@@ -10,7 +10,7 @@
 			marker = L.marker([0, 0]);
 		});
 		describe("when a Marker is added to multiple FeatureGroups ", function () {
-			it("e.layer should be the Marker", function () {
+			it("e.propagatedFrom should be the Marker", function () {
 				var fg1 = L.featureGroup(),
 				    fg2 = L.featureGroup();
 
@@ -21,13 +21,13 @@
 				    wasClicked2;
 
 				fg2.on('click', function (e) {
-					expect(e.layer).to.be(marker);
+					expect(e.propagatedFrom).to.be(marker);
 					expect(e.target).to.be(fg2);
 					wasClicked2 = true;
 				});
 
 				fg1.on('click', function (e) {
-					expect(e.layer).to.be(marker);
+					expect(e.propagatedFrom).to.be(marker);
 					expect(e.target).to.be(fg1);
 					wasClicked1 = true;
 				});

src/core/Events.js

@@ -174,7 +174,11 @@ export var Events = {
 	fire: function (type, data, propagate) {
 		if (!this.listens(type, propagate)) { return this; }
 
-		var event = Util.extend({}, data, {type: type, target: this});
+		var event = Util.extend({}, data, {
+			type: type,
+			target: this,
+			sourceTarget: data && data.sourceTarget || this
+		});
 
 		if (this._events) {
 			var listeners = this._events[type];
@@ -255,7 +259,10 @@ export var Events = {
 
 	_propagateEvent: function (e) {
 		for (var id in this._eventParents) {
-			this._eventParents[id].fire(e.type, Util.extend({layer: e.target}, e), true);
+			this._eventParents[id].fire(e.type, Util.extend({
+				layer: e.target,
+				propagatedFrom: e.target
+			}, e), true);
 		}
 	}
 };

src/core/Events.leafdoc

@@ -21,7 +21,16 @@ The base event object. All other event objects contain these properties too.
 @property type: String
 The event type (e.g. `'click'`).
 @property target: Object
-The object that fired the event.
+The object that fired the event. For propagated events, the last object in
+the propagation chain that fired the event.
+@property sourceTarget: Object
+The object that originally fired the event. For non-propagated events, this will
+be the same as the `target`.
+@property propagatedFrom: Object
+For propagated events, the last object that propagated the event to its
+event parent.
+@property layer: Object
+**Deprecated.** The same as `propagatedFrom`.
 
 
 @miniclass KeyboardEvent (Event objects)