Add observatory_pub_packages snapshot to third_party

observatory_pub_packages/template_binding/template_binding.dart

+// Copyright (c) 2014, 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.
+
+/**
+ * This library provides access to the Polymer project's
+ * [Data Binding](http://www.polymer-project.org/docs/polymer/databinding.html)
+ * Find more information at the
+ * [Polymer.dart homepage](https://www.dartlang.org/polymer-dart/).
+ *
+ * Extends the capabilities of the HTML Template Element by enabling it to
+ * create, manage, and remove instances of content bound to data defined in
+ * Dart.
+ *
+ * Node.bind() is a new method added to all DOM nodes which instructs them to
+ * bind the named property to the data provided. These allows applications to
+ * create a data model in Dart or JavaScript that DOM reacts to.
+ */
+library template_binding;
+
+import 'dart:async';
+import 'dart:collection';
+import 'dart:html';
+import 'dart:js' as js show context;
+import 'dart:js' show JsObject;
+import 'dart:svg' show SvgSvgElement;
+import 'package:observe/observe.dart';
+
+import 'src/mustache_tokens.dart';
+
+part 'src/binding_delegate.dart';
+part 'src/instance_binding_map.dart';
+part 'src/node.dart';
+part 'src/template.dart';
+part 'src/template_iterator.dart';
+
+// TODO(jmesserly): ideally we would split TemplateBinding and Node.bind into
+// two packages, but this is not easy when we are faking extension methods.
+// Since TemplateElement needs to override Node.bind, it seems like the
+// Node.bind layer must have some innate knowledge of TemplateBinding.
+// NOTE: I've heard NodeBind might become an internal API, which is all the more
+// reason to have it in this package.
+
+/**
+ * Provides access to the data binding APIs for the [node]. For example:
+ *
+ *     templateBind(node).model = new MyModel();
+ *
+ * This is equivalent to [nodeBind], but provides access to
+ * [TemplateBindExtension] APIs. [node] should be a [TemplateElement], or
+ * equivalent semantic template such as:
+ *
+ *     <table template repeat="{{row in rows}}">
+ *       <tr template repeat="{{item in row}}">
+ *         <td>{{item}}</td>
+ *       </tr>
+ *     </table>
+ */
+TemplateBindExtension templateBind(Element node) => nodeBind(node);
+
+/**
+ * Like [templateBind], but intended to be used only within a custom element
+ * that implements [TemplateBindExtension]. This method can be used to simulate
+ * a super call. For example:
+ *
+ *     class CoolTemplate extends TemplateElement
+ *         implements TemplateBindExtension {
+ *
+ *       createInstance(model, delegate) {
+ *         // do something cool...
+ *         // otherwise, fall back to superclass
+ *         return templateBindFallback(this).createInstance(model, delegate);
+ *       }
+ *       ...
+ *     }
+ */
+TemplateBindExtension templateBindFallback(Element node) =>
+    nodeBindFallback(node);
+
+/**
+ * Provides access to the data binding APIs for the [node]. For example:
+ *
+ *     nodeBind(node).bind('checked', model, 'path.to.some.value');
+ */
+NodeBindExtension nodeBind(Node node) {
+  return node is NodeBindExtension ? node : nodeBindFallback(node);
+}
+
+/**
+ * Like [nodeBind], but intended to be used only within a custom element that
+ * implements [NodeBindExtension]. This method can be used to simulate a super
+ * call. For example:
+ *
+ *     class FancyButton extends ButtonElement implements NodeBindExtension {
+ *       bind(name, model, path) {
+ *         if (name == 'fancy-prop') ... // do fancy binding
+ *         // otherwise, fall back to superclass
+ *         return nodeBindFallback(this).bind(name, model, path);
+ *       }
+ *       ...
+ *     }
+ */
+NodeBindExtension nodeBindFallback(Node node) {
+  var extension = _expando[node];
+  if (extension != null) return extension;
+
+  if (isSemanticTemplate(node)) {
+    extension = new TemplateBindExtension._(node);
+  } else {
+    extension = new NodeBindExtension._(node);
+  }
+  _expando[node] = extension;
+  return extension;
+}
+
+
+bool _isAttributeTemplate(Element n) => n.attributes.containsKey('template') &&
+    _SEMANTIC_TEMPLATE_TAGS.containsKey(n.localName);
+
+bool _isSvgTemplate(Element el) => el.tagName == 'template' &&
+    el.namespaceUri == 'http://www.w3.org/2000/svg';
+
+bool _isHtmlTemplate(Element el) => el.tagName == 'TEMPLATE' &&
+    el.namespaceUri == 'http://www.w3.org/1999/xhtml';
+
+/**
+ * Returns true if this node is semantically a template.
+ *
+ * A node is a template if [tagName] is TEMPLATE, or the node has the
+ * 'template' attribute and this tag supports attribute form for backwards
+ * compatibility with existing HTML parsers. The nodes that can use attribute
+ * form are table elements (THEAD, TBODY, TFOOT, TH, TR, TD, CAPTION, COLGROUP
+ * and COL), OPTION, and OPTGROUP.
+ */
+bool isSemanticTemplate(Node n) => n is Element &&
+    (_isHtmlTemplate(n) || _isAttributeTemplate(n) || _isSvgTemplate(n));
+
+/** Returns true if this is the staging document for a template. */
+bool isTemplateStagingDocument(Document d) => _isStagingDocument[d] == true;
+
+
+/**
+ * True to enable [NodeBindingExtension.bindings]. This can be used by tools
+ * such as UI builders to easily inspect live bindings. Defaults to false for
+ * performance reasons.
+ */
+bool get enableBindingsReflection =>
+    js.context['Platform']['enableBindingsReflection'] == true;
+
+set enableBindingsReflection(bool value) {
+  js.context['Platform']['enableBindingsReflection'] = value;
+}
+
+// TODO(jmesserly): const set would be better
+const _SEMANTIC_TEMPLATE_TAGS = const {
+  'caption': null,
+  'col': null,
+  'colgroup': null,
+  'option': null,
+  'optgroup': null,
+  'tbody': null,
+  'td': null,
+  'tfoot': null,
+  'th': null,
+  'thead': null,
+  'tr': null,
+};
+
+
+// TODO(jmesserly): investigate if expandos give us enough performance.
+
+// The expando for storing our MDV extensions.
+//
+// In general, we need state associated with the nodes. Rather than having a
+// bunch of individual expandos, we keep one per node.
+//
+// Aside from the potentially helping performance, it also keeps things simpler
+// if we decide to integrate MDV into the DOM later, and means less code needs
+// to worry about expandos.
+final Expando _expando = new Expando('template_binding');