Provide cross-browser Rects for box model dimensions for Elements.

sdk/lib/html/dart2js/html_dart2js.dart

 /// The Dart HTML library.
 ///
 /// For examples, see
 /// [Dart HTML5 Samples](https://github.com/dart-lang/dart-html5-samples)
 /// on Github.
 library dart.dom.html;
 
 import 'dart:async';
 import 'dart:collection';
 import 'dart:_collection-dev' hide Symbol, deprecated;
@@ skipping 7900 matching lines @@
   }
 
   Element get single {
     if (length > 1) throw new StateError("More than one element");
     return first;
   }
 }
 
 /**
  * An immutable list containing HTML elements. This list contains some
- * additional methods for ease of CSS manipulation on a group of elements.
+ * additional methods when compared to regular lists for ease of CSS 
+ * manipulation on a group of elements.
  */
 abstract class ElementList<T extends Element> extends ListBase<T> {
   /**
    * The union of all CSS classes applied to the elements in this list.
    *
    * This set makes it easy to add, remove or toggle (add if not present, remove
    * if present) the classes applied to a collection of elements.
    *
    *     htmlList.classes.add('selected');
    *     htmlList.classes.toggle('isOnline');
    *     htmlList.classes.remove('selected');
    */
   CssClassSet get classes;
 
   /** Replace the classes with `value` for every element in this list. */
   set classes(Iterable<String> value);
+
+  /** 
+   * Access dimensions and position of the Elements in this list.
+   * 
+   * Setting the height or width properties will set the height or width
+   * property for all elements in the list. This returns a rectangle with the 
+   * dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Getting the height or width returns the height or width of the
+   * first Element in this list. 
+   *
+   * Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not.
+   */
+  @Experimental()
+  CssRect get contentEdge;
+  
+  /**
+   * Access dimensions and position of the first Element's content + padding box
+   * in this list.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `innerHeight` value for an element. This
+   * is also a rectangle equalling the dimensions of clientHeight and
+   * clientWidth.
+   */
+  @Experimental()
+  CssRect get paddingEdge;
+
+  /**
+   * Access dimensions and position of the first Element's content + padding +
+   * border box in this list.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  @Experimental()
+  CssRect get borderEdge;
+
+  /**
+   * Access dimensions and position of the first Element's content + padding +
+   * border + margin box in this list.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  @Experimental()
+  CssRect get marginEdge;
 }
 
 // TODO(jacobr): this is an inefficient implementation but it is hard to see
 // a better option given that we cannot quite force NodeList to be an
 // ElementList as there are valid cases where a NodeList JavaScript object
 // contains Node objects that are not Elements.
 class _FrozenElementList<T extends Element> extends ListBase<T> implements ElementList {
   final List<Node> _nodeList;
+  // The subset of _nodeList that are Elements.
+  List<Element> _elementList;
 
-  _FrozenElementList._wrap(this._nodeList);
+  _FrozenElementList._wrap(this._nodeList) {
+    _elementList = _nodeList.where((e) => e is Element);
+  }
 
   int get length => _nodeList.length;
 
   Element operator [](int index) => _nodeList[index];
 
   void operator []=(int index, Element value) {
     throw new UnsupportedError('Cannot modify list');
   }
 
   void set length(int newLength) {
     throw new UnsupportedError('Cannot modify list');
   }
 
   void sort([Comparator<Element> compare]) {
     throw new UnsupportedError('Cannot sort list');
   }
 
   Element get first => _nodeList.first;
 
   Element get last => _nodeList.last;
 
   Element get single => _nodeList.single;
 
-  CssClassSet get classes => new _MultiElementCssClassSet(
-      _nodeList.where((e) => e is Element));
+  CssClassSet get classes => new _MultiElementCssClassSet(_elementList);
 
   void set classes(Iterable<String> value) {
-    _nodeList.where((e) => e is Element).forEach((e) => e.classes = value);
+    _elementList.forEach((e) => e.classes = value);
   }
+
+  CssRect get contentEdge => new _ContentCssListRect(_elementList);
+  
+  CssRect get paddingEdge => _elementList.first.paddingEdge;
+
+  CssRect get borderEdge => _elementList.first.borderEdge;
+
+  CssRect get marginEdge => _elementList.first.marginEdge;
 }
 
 /**
  * An abstract class, which all HTML elements extend.
  */
 @DomName('Element')
 abstract class Element extends Node implements ElementTraversal native "Element" {
 
   /**
    * Creates an HTML element from a valid fragment of HTML.
@@ skipping 681 matching lines @@
   @Experimental()
   bool get isTemplate => tagName == 'TEMPLATE' || _isAttributeTemplate;
 
   void _ensureTemplate() {
     if (!isTemplate) {
       throw new UnsupportedError('$this is not a template.');
     }
     TemplateElement.decorate(this);
   }
 
+  /**
+   * Access this element's content position.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not.
+   * 
+   * Important note: use of this method _will_ perform CSS calculations that can

[Jennifer Messerly, 2013/07/16 22:03:16]

I like this note, but we might want to soften the wording a bit? IMHO, using
these properties for animation is fine, even one of the use cases. The trick is
you don't want to use them _during_ an animation frame. As long as the query is
before the animation starts (or after it finishes), it should be okay.

Perhaps link to this:
https://developers.google.com/speed/articles/reflow

[Emily Fortuna, 2013/07/18 22:45:02]

Done.

+   * trigger a browser reflow. Therefore, use of this property for animation 
+   * calculations is strongly discouraged.
+   */
+  @Experimental()
+  CssRect get contentEdge => new _ContentCssRect(this);
+  
+  /**
+   * Access the dimensions and position of this element's content + padding box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `innerHeight` value for an element. This

[Jennifer Messerly, 2013/07/16 22:03:16]

I wonder if we should link the jQuery docs?

 ... retrieve jQuery's [innerHeight](http://api.jquery.com/innerHeight/) value
for an element. ...

[Emily Fortuna, 2013/07/18 22:45:02]

Done.

+   * is also a rectangle equalling the dimensions of clientHeight and
+   * clientWidth.
+   * 
+   * Important note: use of this method _will_ perform CSS calculations that can
+   * trigger a browser reflow. Therefore, use of this property for animation 
+   * calculations is strongly discouraged.
+   */
+  @Experimental()
+  CssRect get paddingEdge => new _PaddingCssRect(this);
+
+  /**
+   * Access the dimensions and position of this element's content + padding +
+   * border box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   * 
+   * Important note: use of this method _will_ perform CSS calculations that can
+   * trigger a browser reflow. Therefore, use of this property for animation 
+   * calculations is strongly discouraged.
+   */
+  @Experimental()
+  CssRect get borderEdge => new _BorderCssRect(this);
+
+  /**
+   * Access the dimensions and position of this element's content + padding +
+   * border + margin box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   * 
+   * Important note: use of this method _will_ perform CSS calculations that can
+   * trigger a browser reflow. Therefore, use of this property for animation 
+   * calculations is strongly discouraged.
+   */
+  @Experimental()
+  CssRect get marginEdge => new _MarginCssRect(this);
   // To suppress missing implicit constructor warnings.
   factory Element._() { throw new UnsupportedError("Not supported"); }
 
   @DomName('Element.abortEvent')
   @DocsEditable()
   static const EventStreamProvider<Event> abortEvent = const EventStreamProvider<Event>('abort');
 
   @DomName('Element.beforecopyEvent')
   @DocsEditable()
   static const EventStreamProvider<Event> beforeCopyEvent = const EventStreamProvider<Event>('beforecopy');
@@ skipping 18007 matching lines @@
       }
     }
     return s;
   }
 
   void writeClasses(Set<String> s) {
     List list = new List.from(s);
     _element.className = s.join(' ');
   }
 }
+// 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.
+
+
+class _ContentCssRect extends CssRect {
+
+  _ContentCssRect(element) : super(element);

[Jennifer Messerly, 2013/07/16 22:03:16]

newline after this?

[Emily Fortuna, 2013/07/18 22:45:02]

Done.

+  num get height => _element.offsetHeight +
+      _addOrSubtractToBoxModel(CssRect._HEIGHT, 'content');
+
+  num get width => _element.offsetWidth +
+      _addOrSubtractToBoxModel(CssRect._WIDTH, 'content');
+
+  /**
+   * Set the height to `newHeight`.
+   *
+   * Values of newHeight that are less than zero are converted to effectively
+   * setting the height to 0. This is equivalent to the `height`
+   * function in jQuery and the calculated `height` css value, converted to a
+   * num in pixels.
+   */
+  void set height(Dimension newHeight) {
+    if (newHeight.value < 0) newHeight = new Dimension.px(0);
+    _element.style.height = newHeight.toString();
+  }
+
+  /**
+   * Set the current computed width in pixels of this element.
+   *
+   * This is equivalent to the `width` function in jQuery and the calculated
+   * `width` css value, converted to a dimensionless num in pixels.
+   */
+  void set width(Dimension newWidth) {
+    if (newWidth.value < 0) newWidth = new Dimension.px(0);
+    _element.style.width = newWidth.toString();
+  }
+
+  num get left() => _element.getBoundingClientRect().left -
+      _addOrSubtractToBoxModel(['left'], 'content');
+  num get top() => _element.getBoundingClientRect().top -
+      _addOrSubtractToBoxModel(['top'], 'content');
+}
+
+class _ContentCssListRect extends _ContentCssRect {
+  List<Element> _elementList;
+
+  _ContentCssListRect(elementList) : super(elementList.first) {
+    _elementList = elementList;
+  }
+
+  /**
+   * Set the height to `newHeight`.
+   *
+   * Values of newHeight that are less than zero are converted to effectively
+   * setting the height to 0. This is equivalent to the `height`
+   * function in jQuery and the calculated `height` css value, converted to a
+   * num in pixels.
+   */
+  void set height(Dimension newHeight) {
+    _elementList.forEach((e) => e.contentEdge.height = newHeight);
+  }
+
+  /**
+   * Set the current computed width in pixels of this element.
+   *
+   * This is equivalent to the `width` function in jQuery and the calculated
+   * `width` css value, converted to a dimensionless num in pixels.
+   */
+  void set width(Dimension newWidth) {
+    _elementList.forEach((e) => e.contentEdge.width = newWidth);
+  }
+}
+
+class _PaddingCssRect extends CssRect {
+  _PaddingCssRect(element) : super(element);
+  num get height => _element.offsetHeight +
+      _addOrSubtractToBoxModel(CssRect._HEIGHT, 'padding');
+  num get width => _element.offsetWidth +
+      _addOrSubtractToBoxModel(CssRect._WIDTH, 'padding');
+
+  num get left() => _element.getBoundingClientRect().left -
+      _addOrSubtractToBoxModel(['left'], 'padding');
+  num get top() => _element.getBoundingClientRect().top -
+      _addOrSubtractToBoxModel(['top'], 'padding');
+}
+
+class _BorderCssRect extends CssRect {
+  _BorderCssRect(element) : super(element);
+  num get height() => _element.offsetHeight;
+  num get width() => _element.offsetWidth;
+
+  num get left() => _element.getBoundingClientRect().left;
+  num get top() => _element.getBoundingClientRect().top;
+}
+
+class _MarginCssRect extends CssRect {
+  _MarginCssRect(element) : super(element);
+  num get height() => _element.offsetHeight +
+      _addOrSubtractToBoxModel(CssRect._HEIGHT, 'margin');
+  num get width() =>
+      _element.offsetWidth + _addOrSubtractToBoxModel(CssRect._WIDTH, 'margin');
+
+  num get left() => _element.getBoundingClientRect().left -
+      _addOrSubtractToBoxModel(['left'], 'margin');
+  num get top() => _element.getBoundingClientRect().top -
+      _addOrSubtractToBoxModel(['top'], 'margin');
+}
+
+/**
+ * A class for representing CSS dimensions.
+ *
+ * In contrast to the more general purpose [Rect] class, this class's values are
+ * mutable, so one can change the height of an element programmatically.
+ *
+ * SPECIAL NOTE: Do _not_ use these methods of setting or getting dimensions
+ * for animations, as they will trigger a redraw of the layout.
+ */
+abstract class CssRect extends RectBase implements Rect {
+  Element _element;
+
+  CssRect(this._element);
+
+  num get left();
+
+  num get top();
+
+  /**
+   * The height of this rectangle.
+   *
+   * This is equivalent to the `height` function in jQuery and the calculated
+   * `height` css value, converted to a dimensionless num in pixels. Unlike
+   * [getBoundingClientRect], `height` will return the same numerical width if
+   * the element is hidden or not.
+   */
+  num get height();
+
+  /**
+   * The width of this rectangle.
+   *
+   * This is equivalent to the `width` function in jQuery and the calculated
+   * `width` css value, converted to a dimensionless num in pixels. Unlike
+   * [getBoundingClientRect], `width` will return the same numerical width if
+   * the element is hidden or not.
+   */
+  num get width();
+
+  /**
+   * Set the height to `newHeight`.
+   *
+   * Values of newHeight that are less than zero are converted to effectively
+   * setting the height to 0. Note that only the content height can be set via
+   * this method.
+   */
+  void set height(Dimension newHeight) {
+    throw new UnsupportedError("Can only set height for content rect.");
+  }
+
+  /**
+   * Set the current computed width in pixels of this element.
+   *
+   * Note that only the content width can be set via this method.
+   */
+  void set width(Dimension newWidth) {
+    throw new UnsupportedError("Can only set width for content rect.");
+  }
+
+  /**
+   * Return a value that is used to modify the initial height or width
+   * measurement of an element. Depending on the value (ideally an enum) passed
+   * to augmentingMeasurement, we may need to add or subtract margin, padding,
+   * or border values, depending on the measurement we're trying to obtain.
+   */
+  num _addOrSubtractToBoxModel(List<String> dimensions,
+      String augmentingMeasurement) {
+    // getComputedStyle always returns pixel values (hence, computed), so we're
+    // always dealing with pixels in this method.
+    var styles = _element.getComputedStyle();
+
+    var val = 0;
+
+    for (String measurement in dimensions) {
+      // The border-box and default box model both exclude margin in the regular
+      // height/width calculation, so add it if we want it for this measurement.
+      if (augmentingMeasurement == 'margin') {
+        val += new Dimension._(styles.getPropertyValue(
+            '$augmentingMeasurement-$measurement')).value;
+      }
+
+      // The border-box includes padding and border, so remove it if we want
+      // just the content itself.
+      if (augmentingMeasurement == 'content') {
+        val -= new Dimension._(
+            styles.getPropertyValue('padding-$measurement')).value;
+      }
+
+      // At this point, we don't wan't to augment with border or margin,
+      // so remove border.
+      if (augmentingMeasurement != 'margin') {
+              val -= new Dimension._(styles.getPropertyValue(
+            'border-${measurement}-width')).value;
+      }
+    }
+    return val;
+  }
+
+  final static _HEIGHT = ['top', 'bottom'];
+  final static _WIDTH = ['right', 'left'];
+}
+
+/** Class representing a distance measurement in CSS. */
+@Experimental()
+class Dimension {
+  num _value;
+  String _unit;
+
+  /** Set this CSS Dimension to a percentage `value`. */
+  Dimension.percent(this._value) : _unit = '%';
+
+  /** Set this CSS Dimension to a pixel `value`. */
+  Dimension.px(this._value) : _unit = 'px';
+
+  /** Set this CSS Dimension to a pica `value`. */
+  Dimension.pc(this._value) : _unit = 'pc';
+
+  /** Set this CSS Dimension to a point `value`. */
+  Dimension.pt(this._value) : _unit = 'pt';
+
+  /** Set this CSS Dimension to an inch `value`. */
+  Dimension.inch(this._value) : _unit = 'in';
+
+  /** Set this CSS Dimension to a centimeter `value`. */
+  Dimension.cm(this._value) : _unit = 'cm';
+
+  /** Set this CSS Dimension to a millimeter `value`. */
+  Dimension.mm(this._value) : _unit = 'mm';
+
+  /**
+   * Set this CSS Dimension to the specified number of ems.
+   *
+   * 1em is equal to the current font size. (So 2ems is equal to double the font
+   * size). This is useful for producing website layouts that scale nicely with
+   * the user's desired font size.
+   */
+  Dimension.em(this._value) : _unit = 'em';
+
+  /**
+   * Set this CSS Dimension to the specified number of x-heights.
+   *
+   * One ex is equal to the the x-height of a font's baseline to its mean line,
+   * generally the height of the letter "x" in the font, which is usually about
+   * half the font-size.
+   */
+  Dimension.ex(this._value) : _unit = 'ex';
+
+  /**
+   * Construct a Dimension object from the CSS string `cssValue`, in pixels.
+   *  This constructor is only called on output from getComputedValue, which we
+   * know to be pixels.
+   */
+  Dimension._(String pixels = '0px') {
+    if (pixels.contains('.')) {
+      _value = double.parse(pixels.substring(0, pixels.length - 2));
+    } else {
+      _value = int.parse(pixels.substring(0, pixels.length - 2));
+    }
+    _unit = 'px';
+  }
+
+  /** Print out the CSS String representation of this value. */
+  String toString() {
+    return '${_value}${_unit}';
+  }
+
+  /** Return a unitless, numerical value of this CSS value. */
+  num get value => this._value;
+}
 // Copyright (c) 2011, 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.
 
 
 typedef EventListener(Event event);
 // 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.
 
@@ skipping 1497 matching lines @@
    * Indicates the document and all subresources have been loaded.
    */
   static const String COMPLETE = "complete";
 }
 // 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.
 
 
 /**
- * A class for representing two-dimensional rectangles.
+ * A base class for representing two-dimensional rectangles. This will hopefully
+ * be moved merged with the dart:math Rect.
  */
-class Rect {
-  final num left;
-  final num top;
-  final num width;
-  final num height;
-
-  const Rect(this.left, this.top, this.width, this.height);
-
-  factory Rect.fromPoints(Point a, Point b) {
-    var left;
-    var width;
-    if (a.x < b.x) {
-      left = a.x;
-      width = b.x - left;
-    } else {
-      left = b.x;
-      width = a.x - left;
-    }
-    var top;
-    var height;
-    if (a.y < b.y) {
-      top = a.y;
-      height = b.y - top;
-    } else {
-      top = b.y;
-      height = a.y - top;
-    }
-
-    return new Rect(left, top, width, height);
-  }
+// TODO(efortuna): Merge with Math rect after finalizing with Florian.
+abstract class RectBase {
+  num get left;
+  num get top;
+  num get width;
+  num get height;
 
   num get right => left + width;
   num get bottom => top + height;
 
   // NOTE! All code below should be common with Rect.
-  // TODO: implement with mixins when available.
 
   String toString() {
     return '($left, $top, $width, $height)';
   }
 
   bool operator ==(other) {
     if (other is !Rect) return false;
     return left == other.left && top == other.top && width == other.width &&
         height == other.height;
   }
@@ skipping 73 matching lines @@
    * Truncates coordinates to integers and returns the result as a new
    * rectangle.
    */
   Rect toInt() => new Rect(left.toInt(), top.toInt(), width.toInt(),
       height.toInt());
 
   Point get topLeft => new Point(this.left, this.top);
   Point get bottomRight => new Point(this.left + this.width,
       this.top + this.height);
 }
+
+
+
+/**
+ * A class for representing two-dimensional rectangles.
+ */
+class Rect extends RectBase {
+  final num left;
+  final num top;
+  final num width;
+  final num height;
+
+  const Rect(this.left, this.top, this.width, this.height);
+
+  factory Rect.fromPoints(Point a, Point b) {
+    var left;
+    var width;
+    if (a.x < b.x) {
+      left = a.x;
+      width = b.x - left;
+    } else {
+      left = b.x;
+      width = a.x - left;
+    }
+    var top;
+    var height;
+    if (a.y < b.y) {
+      top = a.y;
+      height = b.y - top;
+    } else {
+      top = b.y;
+      height = a.y - top;
+    }
+
+    return new Rect(left, top, width, height);
+  }
+}
 // Copyright (c) 2012, 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.
 
 
 class _HttpRequestUtils {
 
   // Helper for factory HttpRequest.get
   static HttpRequest get(String url,
                             onComplete(HttpRequest request),
@@ skipping 1102 matching lines @@
       _position = nextPosition;
       return true;
     }
     _current = null;
     _position = _array.length;
     return false;
   }
 
   T get current => _current;
 }