Add Event delegation to Elements and groups of elements.

tools/dom/src/EventStreamProvider.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of html;
 
 /**
  * Adapter for exposing DOM events as Dart streams.
  */
 class _EventStream<T extends Event> extends Stream<T> {
@@ skipping 12 matching lines @@
   StreamSubscription<T> listen(void onData(T event),
       { void onError(error),
         void onDone(),
         bool cancelOnError}) {
 
     return new _EventStreamSubscription<T>(
         this._target, this._eventType, onData, this._useCapture);
   }
 }
 
+/** A specialized Stream available to [Element]s to enable event delegation. */
+abstract class ElementStream<T extends Event> implements Stream<T> {
+
+  /**
+   * Return a stream that only fires when the particular event fires for
+   * elements matching the specified CSS selector.
+   *
+   * This is the Dart equivalent to jQuery's
+   * [delegate](http://api.jquery.com/delegate/).
+   */
+  Stream<T> filter(String selector) =>

[blois, 2013/08/02 20:13:02]

Filter seems a bit generic for Streams (I could easily see it have different
uses elswhere).

How about matchesSelector? or matches (follows Element)?

[Emily Fortuna, 2013/08/07 23:38:25]

Done.

+      this.where((event) => event.target.matches(selector));

[blois, 2013/08/02 20:21:25]

Also, see the discussion in the bug about the ancestor tree- I think this is a
critical aspect of the function.

For example:
  <div class='clickable'>
    <div>something</div>
  </div>

  document.body.onClick.filter('.clickable')

This would yield no click events since the element that the clicks occur on (the
inner div) does not match the selector.

[Emily Fortuna, 2013/08/07 23:38:25]

Done.

+}
+
+/**
+ * Adapter for exposing DOM Element events as streams, while also allowing
+ * event delegation.
+ */
+class _ElementEventStreamImpl<T extends Event> extends _EventStream<T> with

[blois, 2013/08/02 20:13:02]

Rather than the mixin, how about just declare filter on ElementStream, but put
the implementation here. Generated code should be simpler/smaller.

So:
class _ElementEventStreamImpl<T extends Event> extends _EventStream<T>
implements ElementStream<T> {}

[Emily Fortuna, 2013/08/07 23:38:25]

True, but then we have to write the identical code in
_ElementListEventStreamImpl (though it's not a lot of code, so not a huge
deal...). Sure, it produces less code, but is the new version actually better on
the maintainable code that developers see?

+    ElementStream<T> {
+  _ElementEventStreamImpl(target, eventType, useCapture) :
+      super(target, eventType, useCapture);
+}
+
+/**
+ * Adapter for exposing events on a collection of DOM Elements as streams,
+ * while also allowing event delegation.
+ */
+class _ElementListEventStreamImpl<T extends Event> extends Stream<T> with

[Jennifer Messerly, 2013/08/02 19:31:59]

should this be "implements Stream"? it looks like most (all?) of the methods are
being forwarded.

[blois, 2013/08/02 20:13:02]

Can this be made more generic- a Stream which combines a bunch of other streams
into one? I know pub has a version which combines 2 streams, not sure if there's
an impl around which combines many.

Then just a subclass for ElementStream which adds the filtering?

[Emily Fortuna, 2013/08/07 23:38:25]

Done.

[Emily Fortuna, 2013/08/07 23:38:25]

Done.

+    ElementStream<T> {
+
+  StreamController _controller;
+
+  _ElementListEventStreamImpl(targetList, eventType, useCapture) {
+    _controller = new StreamController(sync: true);

[Jennifer Messerly, 2013/08/02 19:31:59]

should this be a broadcast stream?

[Emily Fortuna, 2013/08/07 23:38:25]

yes, thank you. done.

+    for (Element target in targetList) {
+      var stream = new _EventStream(target, eventType, useCapture);

[Jennifer Messerly, 2013/08/02 19:31:59]

hmm, it looks like these listeners are never released?

I think you can use onListen and onCancel here, something like:


List _subscriptions;

_ElementListEventStreamImpl(...)
{
  _controller = new StreamController(sync: true, onListen: _onListen, onCancel:
_onCancel);
}

/// Called the first time a listener is added to this object
_onListen() {
  _subscriptions = [];
  for (Element target in targetList) {
    var stream = ...
    _subscriptions.add(stream.listen(...));
  }
}

/// Called when the last subscription for this object is cancelled
_onCancel() {
  for (var sub in _subscriptions) sub.cancel();
  _subscriptions = null;
}

[blois, 2013/08/02 20:13:02]

See
https://codereview.chromium.org/12220003/diff/6/tools/dom/src/EventStreamProv...
for an earlier CL with this.

[Emily Fortuna, 2013/08/07 23:38:25]

Done.

+      stream.listen((event) {
+        _controller.add(event);
+        return event;
+      });
+    }
+  }
+
+  // Delegate all regular Stream behavor to our wrapped Stream.
+  StreamSubscription<T> listen(void onData(T event),
+      { void onError(error),
+        void onDone(),
+        bool cancelOnError}) =>
+      _controller.stream.listen(onData, onError: onError, onDone: onDone,

[Jennifer Messerly, 2013/08/02 19:31:59]

it is probably worth caching "_controller.stream". it appears that it allocates
a new object each time. (from stream_controller.dart)

[Emily Fortuna, 2013/08/07 23:38:25]

Done.

+          cancelOnError: cancelOnError);
+  Stream<T> asBroadcastStream({void onListen(StreamSubscription subscription),
+                               void onCancel(StreamSubscription subscription)})
+      => _controller.stream;
+  bool get isBroadcast => true;
+  Stream<T> where(bool test(T event)) => _controller.stream.where(test);
+  Stream map(convert(T event)) => _controller.stream.map(convert);

[blois, 2013/08/02 20:13:02]

Is it necessary to override all of these? Seems like only the listen() method
should need to be overridden.

[Emily Fortuna, 2013/08/07 23:38:25]

Since it's not actually a Stream and just implements stream.

+  Stream<T> handleError(void handle( error), { bool test(error) }) =>
+      _controller.stream.handleError(handle, test: test);
+  Stream expand(Iterable convert(T value)) =>
+      _controller.stream.expand(convert);
+  Future pipe(StreamConsumer<T> streamConsumer) =>
+      _controller.stream.pipe(streamConsumer);
+  Stream transform(StreamTransformer<T, dynamic> streamTransformer) =>
+      _controller.stream.transform(streamTransformer);
+  Future<T> reduce(T combine(T previous, T element)) =>
+      _controller.stream.reduce(combine);
+  Future fold(var initialValue, combine(var previous, T element)) =>
+      _controller.stream.fold(initialValue, combine);
+  Future<String> join([String separator = ""]) =>
+      _controller.stream.join(separator);
+  Future<bool> contains(Object needle) => _controller.stream.contains(needle);
+  Future forEach(void action(T element)) => _controller.stream.forEach(action);
+  Future<bool> every(bool test(T element)) => _controller.stream.every(test);
+  Future<bool> any(bool test(T element)) => _controller.stream.any(test);
+  Future<int> get length => _controller.stream.length;
+  Future<bool> get isEmpty => _controller.stream.isEmpty;
+  Future<List<T>> toList() => _controller.stream.toList();
+  Future<Set<T>> toSet() => _controller.stream.toSet();
+  Future drain([var futureValue]) => _controller.stream.drain(futureValue);
+  Stream<T> take(int count) => _controller.stream.take(count);
+  Stream<T> takeWhile(bool test(T element)) =>
+      _controller.stream.takeWhile(test);
+  Stream<T> skip(int count) => _controller.stream.skip(count);
+  Stream<T> skipWhile(bool test(T element)) =>
+      _controller.stream.skipWhile(test);
+  Stream<T> distinct([bool equals(T previous, T next)]) =>
+      _controller.stream.distinct(equals);
+  Future<T> get first => _controller.stream.first;
+  Future<T> get last => _controller.stream.last;
+  Future<T> get single => _controller.stream.single;
+  Future<dynamic> firstWhere(bool test(T element), {Object defaultValue()}) =>
+      _controller.stream.firstWhere(test, defaultValue: defaultValue);
+  Future<dynamic> lastWhere(bool test(T element), {Object defaultValue()}) =>
+      _controller.stream.lastWhere(test, defaultValue: defaultValue);
+  Future<T> singleWhere(bool test(T element)) =>
+      _controller.stream.singleWhere(test);
+  Future<T> elementAt(int index) => _controller.stream.elementAt(index);
+}
+
 class _EventStreamSubscription<T extends Event> extends StreamSubscription<T> {
   int _pauseCount = 0;
   EventTarget _target;
   final String _eventType;
   var _onData;
   final bool _useCapture;
 
   _EventStreamSubscription(this._target, this._eventType, this._onData,
       this._useCapture) {
     _tryResume();
@@ skipping 57 matching lines @@
     }
   }
 
   Future asFuture([var futureValue]) {
     // We just need a future that will never succeed or fail.
     Completer completer = new Completer();
     return completer.future;
   }
 }
 
-
 /**
  * A factory to expose DOM events as Streams.
  */
 class EventStreamProvider<T extends Event> {
   final String _eventType;
 
   const EventStreamProvider(this._eventType);
 
   /**
    * Gets a [Stream] for this event type, on the specified target.
    *
    * This will always return a broadcast stream so multiple listeners can be
    * used simultaneously.
    *
    * This may be used to capture DOM events:
    *
    *     Element.keyDownEvent.forTarget(element, useCapture: true).listen(...);
    *
    * Or for listening to an event which will bubble through the DOM tree:
    *
    *     MediaElement.pauseEvent.forTarget(document.body).listen(...);
    *
    * See also:
    *
    * [addEventListener](http://docs.webplatform.org/wiki/dom/methods/addEventListener)
    */
   Stream<T> forTarget(EventTarget e, {bool useCapture: false}) {

[blois, 2013/08/02 20:13:02]

Since the signature is still returning Stream<T>, why have return a sub-type?
Users shouldn't rely on it since it's not guaranteed by the API.

[Emily Fortuna, 2013/08/07 23:38:25]

But we should expect Element Event streams to always allow delegation. 

-    return new _EventStream(e, _eventType, useCapture);
+    if (e is Element) {
+      return new _ElementEventStreamImpl(e, _eventType, useCapture);
+    } else {
+      return new _EventStream(e, _eventType, useCapture);
+    }
   }
 
   /**
+   * Gets an [ElementEventStream] for this event type, on the specified element.
+   *
+   * This will always return a broadcast stream so multiple listeners can be
+   * used simultaneously.
+   *
+   * This may be used to capture DOM events:
+   *
+   *     Element.keyDownEvent.forElementTarget(element, useCapture: true).listen(...);
+   *
+   * See also:
+   *
+   * [addEventListener](http://docs.webplatform.org/wiki/dom/methods/addEventListener)
+   */
+  ElementStream<T> forElementTarget(Element e, {bool useCapture: false}) {
+    return new _ElementEventStreamImpl(e, _eventType, useCapture);
+  }
+
+  /**
+   * Gets an [ElementEventStream] for this event type, on the list of elements.
+   *
+   * This will always return a broadcast stream so multiple listeners can be
+   * used simultaneously.
+   *
+   * This may be used to capture DOM events:
+   *
+   *     Element.keyDownEvent._forElementTargetList(element, useCapture: true).listen(...);
+   *
+   * See also:
+   *
+   * [addEventListener](http://docs.webplatform.org/wiki/dom/methods/addEventListener)
+   */
+  ElementStream<T> _forElementTargetList(ElementList e,
+      {bool useCapture: false}) {
+    return new _ElementListEventStreamImpl(e, _eventType, useCapture);
+  }
+
+  /**
    * Gets the type of the event which this would listen for on the specified
    * event target.
    *
    * The target is necessary because some browsers may use different event names
    * for the same purpose and the target allows differentiating browser support.
    */
   String getEventType(EventTarget target) {
     return _eventType;
   }
 }
 
 /**
  * A factory to expose DOM events as streams, where the DOM event name has to
  * be determined on the fly (for example, mouse wheel events).
  */
 class _CustomEventStreamProvider<T extends Event>
     implements EventStreamProvider<T> {
 
   final _eventTypeGetter;
   const _CustomEventStreamProvider(this._eventTypeGetter);
 
   Stream<T> forTarget(EventTarget e, {bool useCapture: false}) {
     return new _EventStream(e, _eventTypeGetter(e), useCapture);
   }
 
+  ElementStream<T> forElementTarget(Element e, {bool useCapture: false}) {
+    return new _ElementEventStreamImpl(e, _eventTypeGetter(e), useCapture);
+  }
+
+  ElementStream<T> _forElementTargetList(ElementList e,
+      {bool useCapture: false}) {
+    return new _ElementListEventStreamImpl(e, _eventTypeGetter(e), useCapture);
+  }
+
   String getEventType(EventTarget target) {
     return _eventTypeGetter(target);
   }
 }