Added offset document measurement to Element.

tools/dom/templates/html/impl/impl_Element.darttemplate

Index: tools/dom/templates/html/impl/impl_Element.darttemplate
diff --git a/tools/dom/templates/html/impl/impl_Element.darttemplate b/tools/dom/templates/html/impl/impl_Element.darttemplate
index c64cb74a36a7824b10bceac952d751b49e1a746a..45523a03665bd2c2429beaa6a2e97e778c55dc8f 100644
--- a/tools/dom/templates/html/impl/impl_Element.darttemplate
+++ b/tools/dom/templates/html/impl/impl_Element.darttemplate
@@ -1090,6 +1090,43 @@ $endif
    */
   @Experimental()
   CssRect get marginEdge => new _MarginCssRect(this);
+
+  /** 
+   * Provides the coordinates of the element relative to the top of the 
+   * document. 
+   *
+   * This method is the Dart equivalent to jQuery's 
+   * [offset](http://api.jquery.com/offset/) method.
+   */
+  Point get docOffset => offsetTo(document.documentElement);

[Jennifer Messerly, 2013/07/24 23:26:23]

personally, I would call this "documentOffset". That name seems more consistent
with the existing DOM APIs (e.g. documentElement)

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+
+  /** 
+   * Provides the offset of this element's [borderEdge] relative to the
+   * specified [parent].
+   * 
+   * This is the Dart equivalent of jQuery's
+   * [position](http://api.jquery.com/position/) method. Unlike jQuery's
+   * position, however, [parent] can be any parent element of `this`, 
+   * rather than only `this`'s immediate offsetParent. If the specified element
+   * is _not_ an offset parent or transitive offset parent to this element,
+   * an ArgumentError is thrown.

[Jennifer Messerly, 2013/07/24 23:26:23]

could use code links for [ArgumentError] and [offsetParent]

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+   */
+  Point offsetTo(Element parent) {
+    return _offsetToHelper(this, 
+        parent, parent == this || parent.tagName == 'HTML');

[Jennifer Messerly, 2013/07/24 23:26:23]

can we remove this extra arg? suggestion below.

[Jennifer Messerly, 2013/07/24 23:26:23]

use "identical(parent, this)"? one thing to watch out for with CustomElements...
once we can "extend Element", we might be able to override equals :)

+  }
+
+  Point _offsetToHelper(Element current, Element parent, bool foundAsParent) {

[Jennifer Messerly, 2013/07/24 23:26:23]

can this be static?

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+    if (current == null || current == parent) {

[Jennifer Messerly, 2013/07/24 23:26:23]

can we remove "foundAsParent"? it seems to duplicate what this is already
checking.

it seems like this is equivalent:

Point _offsetToHelper(Element current, Element parent) {
  bool foundAsParent = identical(current, parent) || parent.tagName == 'HTML';
  if (current == null || identical(current, parent)) {
    if (foundAsParent) return new Point(0, 0);
    throw new ArgumentError(...);
  }
  ...
}

there's probably a little more refactoring there; it seems like the
ArgumentError can only be thrown if (current == null && parent.tagName !=
'HTML')

I'm not quite clear what the special case is for tagname HTML--is it basically
saying that even if the node isn't attached to the document, we'll pretend it is
for the purpose of "offsetTo"? Might be good to add that to the comment.

[Emily Fortuna, 2013/07/25 00:20:07]

HTML discussed offline and added comment. and refactored!

+      return foundAsParent? new Point(0, 0) : throw new ArgumentError(

[Jennifer Messerly, 2013/07/24 23:26:23]

this might be cleaner as:

if (foundAsParent) return new Point(0, 0);
throw new ArgumentError( ... );

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+          "Specified element is not a transitive offset parent of this "
+          "element.");
+    } 
+    Element parentOffset = current.offsetParent;
+    Point p = _offsetToHelper(
+        parentOffset, parent, foundAsParent || parentOffset == parent);
+    return new Point(p.x + current.offsetLeft, p.y + current.offsetTop);
+  }
 $!MEMBERS
 }