big update to observe, template_binding, polymer

pkg/observe/lib/src/bindable.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.
+
+library observe.src.bindable;
+
+/// An object that can be data bound.
+// Normally this is used with 'package:template_binding'.
+// TODO(jmesserly): Node.bind polyfill calls this "observable"
+abstract class Bindable {
+  // TODO(jmesserly): since we have "value", should open be a void method?
+  // TODO(jmesserly): not sure how I feel about open taking a variable number
+  // of arguments, but it's the easiest way to make CompoundObserver work.
+
+  /// Initiates observation and returns the initial value.
+  /// The callback will be called with the updated [value].
+  ///
+  /// Some subtypes may chose to provide additional arguments, such as
+  /// [PathObserver] providing the old value as the second argument.
+  /// However, they must support callbacks with as few as 0 or 1 argument.
+  /// This can be implemented by performing an "is" type test on the callback.
+  open(callback);
+
+  /// Stops future notifications and frees the reference to the callback passed
+  /// to [open], so its memory can be collected even if this Bindable is alive.
+  void close();
+
+  /// Gets the current value of the bindings.
+  get value;
+
+  /// This can be implemented for two-way bindings. By default does nothing.
+  /// Note: setting the value of a [Bindable] must not call the [callback] with
+  /// the new value. Any pending change notifications must be discarded.
+  set value(newValue) {}
+}