rubyvis 0.1.0 → 0.1.1

data/vendor/src/color/Colors.js

@@ -0,0 +1,135 @@
+/**
+ * Returns a new categorical color encoding using the specified colors.  The
+ * arguments to this method are an array of colors; see {@link pv.color}. For
+ * example, to create a categorical color encoding using the <tt>species</tt>
+ * attribute:
+ *
+ * <pre>pv.colors("red", "green", "blue").by(function(d) d.species)</pre>
+ *
+ * The result of this expression can be used as a fill- or stroke-style
+ * property. This assumes that the data's <tt>species</tt> attribute is a
+ * string.
+ *
+ * @param {string} colors... categorical colors.
+ * @see pv.Scale.ordinal
+ * @returns {pv.Scale.ordinal} an ordinal color scale.
+ */
+pv.colors = function() {
+  var scale = pv.Scale.ordinal();
+  scale.range.apply(scale, arguments);
+  return scale;
+};
+
+/**
+ * A collection of standard color palettes for categorical encoding.
+ *
+ * @namespace A collection of standard color palettes for categorical encoding.
+ */
+pv.Colors = {};
+
+/**
+ * Returns a new 10-color scheme. The arguments to this constructor are
+ * optional, and equivalent to calling {@link pv.Scale.OrdinalScale#domain}. The
+ * following colors are used:
+ *
+ * <div style="background:#1f77b4;">#1f77b4</div>
+ * <div style="background:#ff7f0e;">#ff7f0e</div>
+ * <div style="background:#2ca02c;">#2ca02c</div>
+ * <div style="background:#d62728;">#d62728</div>
+ * <div style="background:#9467bd;">#9467bd</div>
+ * <div style="background:#8c564b;">#8c564b</div>
+ * <div style="background:#e377c2;">#e377c2</div>
+ * <div style="background:#7f7f7f;">#7f7f7f</div>
+ * <div style="background:#bcbd22;">#bcbd22</div>
+ * <div style="background:#17becf;">#17becf</div>
+ *
+ * @param {number...} domain... domain values.
+ * @returns {pv.Scale.ordinal} a new ordinal color scale.
+ * @see pv.color
+ */
+pv.Colors.category10 = function() {
+  var scale = pv.colors(
+      "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd",
+      "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf");
+  scale.domain.apply(scale, arguments);
+  return scale;
+};
+
+/**
+ * Returns a new 20-color scheme. The arguments to this constructor are
+ * optional, and equivalent to calling {@link pv.Scale.OrdinalScale#domain}. The
+ * following colors are used:
+ *
+ * <div style="background:#1f77b4;">#1f77b4</div>
+ * <div style="background:#aec7e8;">#aec7e8</div>
+ * <div style="background:#ff7f0e;">#ff7f0e</div>
+ * <div style="background:#ffbb78;">#ffbb78</div>
+ * <div style="background:#2ca02c;">#2ca02c</div>
+ * <div style="background:#98df8a;">#98df8a</div>
+ * <div style="background:#d62728;">#d62728</div>
+ * <div style="background:#ff9896;">#ff9896</div>
+ * <div style="background:#9467bd;">#9467bd</div>
+ * <div style="background:#c5b0d5;">#c5b0d5</div>
+ * <div style="background:#8c564b;">#8c564b</div>
+ * <div style="background:#c49c94;">#c49c94</div>
+ * <div style="background:#e377c2;">#e377c2</div>
+ * <div style="background:#f7b6d2;">#f7b6d2</div>
+ * <div style="background:#7f7f7f;">#7f7f7f</div>
+ * <div style="background:#c7c7c7;">#c7c7c7</div>
+ * <div style="background:#bcbd22;">#bcbd22</div>
+ * <div style="background:#dbdb8d;">#dbdb8d</div>
+ * <div style="background:#17becf;">#17becf</div>
+ * <div style="background:#9edae5;">#9edae5</div>
+ *
+ * @param {number...} domain... domain values.
+ * @returns {pv.Scale.ordinal} a new ordinal color scale.
+ * @see pv.color
+*/
+pv.Colors.category20 = function() {
+  var scale = pv.colors(
+      "#1f77b4", "#aec7e8", "#ff7f0e", "#ffbb78", "#2ca02c",
+      "#98df8a", "#d62728", "#ff9896", "#9467bd", "#c5b0d5",
+      "#8c564b", "#c49c94", "#e377c2", "#f7b6d2", "#7f7f7f",
+      "#c7c7c7", "#bcbd22", "#dbdb8d", "#17becf", "#9edae5");
+  scale.domain.apply(scale, arguments);
+  return scale;
+};
+
+/**
+ * Returns a new alternative 19-color scheme. The arguments to this constructor
+ * are optional, and equivalent to calling
+ * {@link pv.Scale.OrdinalScale#domain}. The following colors are used:
+ *
+ * <div style="background:#9c9ede;">#9c9ede</div>
+ * <div style="background:#7375b5;">#7375b5</div>
+ * <div style="background:#4a5584;">#4a5584</div>
+ * <div style="background:#cedb9c;">#cedb9c</div>
+ * <div style="background:#b5cf6b;">#b5cf6b</div>
+ * <div style="background:#8ca252;">#8ca252</div>
+ * <div style="background:#637939;">#637939</div>
+ * <div style="background:#e7cb94;">#e7cb94</div>
+ * <div style="background:#e7ba52;">#e7ba52</div>
+ * <div style="background:#bd9e39;">#bd9e39</div>
+ * <div style="background:#8c6d31;">#8c6d31</div>
+ * <div style="background:#e7969c;">#e7969c</div>
+ * <div style="background:#d6616b;">#d6616b</div>
+ * <div style="background:#ad494a;">#ad494a</div>
+ * <div style="background:#843c39;">#843c39</div>
+ * <div style="background:#de9ed6;">#de9ed6</div>
+ * <div style="background:#ce6dbd;">#ce6dbd</div>
+ * <div style="background:#a55194;">#a55194</div>
+ * <div style="background:#7b4173;">#7b4173</div>
+ *
+ * @param {number...} domain... domain values.
+ * @returns {pv.Scale.ordinal} a new ordinal color scale.
+ * @see pv.color
+ */
+pv.Colors.category19 = function() {
+  var scale = pv.colors(
+      "#9c9ede", "#7375b5", "#4a5584", "#cedb9c", "#b5cf6b",
+      "#8ca252", "#637939", "#e7cb94", "#e7ba52", "#bd9e39",
+      "#8c6d31", "#e7969c", "#d6616b", "#ad494a", "#843c39",
+      "#de9ed6", "#ce6dbd", "#a55194", "#7b4173");
+  scale.domain.apply(scale, arguments);
+  return scale;
+};

data/vendor/src/color/Ramp.js

@@ -0,0 +1,17 @@
+/**
+ * Returns a linear color ramp from the specified <tt>start</tt> color to the
+ * specified <tt>end</tt> color. The color arguments may be specified either as
+ * <tt>string</tt>s or as {@link pv.Color}s. This is equivalent to:
+ *
+ * <pre>    pv.Scale.linear().domain(0, 1).range(...)</pre>
+ *
+ * @param {string} start the start color; may be a <tt>pv.Color</tt>.
+ * @param {string} end the end color; may be a <tt>pv.Color</tt>.
+ * @returns {Function} a color ramp from <tt>start</tt> to <tt>end</tt>.
+ * @see pv.Scale.linear
+ */
+pv.ramp = function(start, end) {
+  var scale = pv.Scale.linear();
+  scale.range.apply(scale, arguments);
+  return scale;
+};

data/vendor/src/data/Arrays.js

@@ -0,0 +1,277 @@
+/**
+ * @private A private variant of Array.prototype.map that supports the index
+ * property.
+ */
+pv.map = function(array, f) {
+  var o = {};
+  return f
+      ? array.map(function(d, i) { o.index = i; return f.call(o, d); })
+      : array.slice();
+};
+
+/**
+ * Concatenates the specified array with itself <i>n</i> times. For example,
+ * <tt>pv.repeat([1, 2])</tt> returns [1, 2, 1, 2].
+ *
+ * @param {array} a an array.
+ * @param {number} [n] the number of times to repeat; defaults to two.
+ * @returns {array} an array that repeats the specified array.
+ */
+pv.repeat = function(array, n) {
+  if (arguments.length == 1) n = 2;
+  return pv.blend(pv.range(n).map(function() { return array; }));
+};
+
+/**
+ * Given two arrays <tt>a</tt> and <tt>b</tt>, <style
+ * type="text/css">sub{line-height:0}</style> returns an array of all possible
+ * pairs of elements [a<sub>i</sub>, b<sub>j</sub>]. The outer loop is on array
+ * <i>a</i>, while the inner loop is on <i>b</i>, such that the order of
+ * returned elements is [a<sub>0</sub>, b<sub>0</sub>], [a<sub>0</sub>,
+ * b<sub>1</sub>], ... [a<sub>0</sub>, b<sub>m</sub>], [a<sub>1</sub>,
+ * b<sub>0</sub>], [a<sub>1</sub>, b<sub>1</sub>], ... [a<sub>1</sub>,
+ * b<sub>m</sub>], ... [a<sub>n</sub>, b<sub>m</sub>]. If either array is empty,
+ * an empty array is returned.
+ *
+ * @param {array} a an array.
+ * @param {array} b an array.
+ * @returns {array} an array of pairs of elements in <tt>a</tt> and <tt>b</tt>.
+ */
+pv.cross = function(a, b) {
+  var array = [];
+  for (var i = 0, n = a.length, m = b.length; i < n; i++) {
+    for (var j = 0, x = a[i]; j < m; j++) {
+      array.push([x, b[j]]);
+    }
+  }
+  return array;
+};
+
+/**
+ * Given the specified array of arrays, concatenates the arrays into a single
+ * array. If the individual arrays are explicitly known, an alternative to blend
+ * is to use JavaScript's <tt>concat</tt> method directly. These two equivalent
+ * expressions:<ul>
+ *
+ * <li><tt>pv.blend([[1, 2, 3], ["a", "b", "c"]])</tt>
+ * <li><tt>[1, 2, 3].concat(["a", "b", "c"])</tt>
+ *
+ * </ul>return [1, 2, 3, "a", "b", "c"].
+ *
+ * @param {array[]} arrays an array of arrays.
+ * @returns {array} an array containing all the elements of each array in
+ * <tt>arrays</tt>.
+ */
+pv.blend = function(arrays) {
+  return Array.prototype.concat.apply([], arrays);
+};
+
+/**
+ * Given the specified array of arrays, <style
+ * type="text/css">sub{line-height:0}</style> transposes each element
+ * array<sub>ij</sub> with array<sub>ji</sub>. If the array has dimensions
+ * <i>n</i>&times;<i>m</i>, it will have dimensions <i>m</i>&times;<i>n</i>
+ * after this method returns. This method transposes the elements of the array
+ * in place, mutating the array, and returning a reference to the array.
+ *
+ * @param {array[]} arrays an array of arrays.
+ * @returns {array[]} the passed-in array, after transposing the elements.
+ */
+pv.transpose = function(arrays) {
+  var n = arrays.length, m = pv.max(arrays, function(d) { return d.length; });
+
+  if (m > n) {
+    arrays.length = m;
+    for (var i = n; i < m; i++) {
+      arrays[i] = new Array(n);
+    }
+    for (var i = 0; i < n; i++) {
+      for (var j = i + 1; j < m; j++) {
+        var t = arrays[i][j];
+        arrays[i][j] = arrays[j][i];
+        arrays[j][i] = t;
+      }
+    }
+  } else {
+    for (var i = 0; i < m; i++) {
+      arrays[i].length = n;
+    }
+    for (var i = 0; i < n; i++) {
+      for (var j = 0; j < i; j++) {
+        var t = arrays[i][j];
+        arrays[i][j] = arrays[j][i];
+        arrays[j][i] = t;
+      }
+    }
+  }
+
+  arrays.length = m;
+  for (var i = 0; i < m; i++) {
+    arrays[i].length = n;
+  }
+
+  return arrays;
+};
+
+/**
+ * Returns a normalized copy of the specified array, such that the sum of the
+ * returned elements sum to one. If the specified array is not an array of
+ * numbers, an optional accessor function <tt>f</tt> can be specified to map the
+ * elements to numbers. For example, if <tt>array</tt> is an array of objects,
+ * and each object has a numeric property "foo", the expression
+ *
+ * <pre>pv.normalize(array, function(d) d.foo)</pre>
+ *
+ * returns a normalized array on the "foo" property. If an accessor function is
+ * not specified, the identity function is used. Accessor functions can refer to
+ * <tt>this.index</tt>.
+ *
+ * @param {array} array an array of objects, or numbers.
+ * @param {function} [f] an optional accessor function.
+ * @returns {number[]} an array of numbers that sums to one.
+ */
+pv.normalize = function(array, f) {
+  var norm = pv.map(array, f), sum = pv.sum(norm);
+  for (var i = 0; i < norm.length; i++) norm[i] /= sum;
+  return norm;
+};
+
+/**
+ * Returns a permutation of the specified array, using the specified array of
+ * indexes. The returned array contains the corresponding element in
+ * <tt>array</tt> for each index in <tt>indexes</tt>, in order. For example,
+ *
+ * <pre>pv.permute(["a", "b", "c"], [1, 2, 0])</pre>
+ *
+ * returns <tt>["b", "c", "a"]</tt>. It is acceptable for the array of indexes
+ * to be a different length from the array of elements, and for indexes to be
+ * duplicated or omitted. The optional accessor function <tt>f</tt> can be used
+ * to perform a simultaneous mapping of the array elements. Accessor functions
+ * can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array.
+ * @param {number[]} indexes an array of indexes into <tt>array</tt>.
+ * @param {function} [f] an optional accessor function.
+ * @returns {array} an array of elements from <tt>array</tt>; a permutation.
+ */
+pv.permute = function(array, indexes, f) {
+  if (!f) f = pv.identity;
+  var p = new Array(indexes.length), o = {};
+  indexes.forEach(function(j, i) { o.index = j; p[i] = f.call(o, array[j]); });
+  return p;
+};
+
+/**
+ * Returns a map from key to index for the specified <tt>keys</tt> array. For
+ * example,
+ *
+ * <pre>pv.numerate(["a", "b", "c"])</pre>
+ *
+ * returns <tt>{a: 0, b: 1, c: 2}</tt>. Note that since JavaScript maps only
+ * support string keys, <tt>keys</tt> must contain strings, or other values that
+ * naturally map to distinct string values. Alternatively, an optional accessor
+ * function <tt>f</tt> can be specified to compute the string key for the given
+ * element. Accessor functions can refer to <tt>this.index</tt>.
+ *
+ * @param {array} keys an array, usually of string keys.
+ * @param {function} [f] an optional key function.
+ * @returns a map from key to index.
+ */
+pv.numerate = function(keys, f) {
+  if (!f) f = pv.identity;
+  var map = {}, o = {};
+  keys.forEach(function(x, i) { o.index = i; map[f.call(o, x)] = i; });
+  return map;
+};
+
+/**
+ * Returns the unique elements in the specified array, in the order they appear.
+ * Note that since JavaScript maps only support string keys, <tt>array</tt> must
+ * contain strings, or other values that naturally map to distinct string
+ * values. Alternatively, an optional accessor function <tt>f</tt> can be
+ * specified to compute the string key for the given element. Accessor functions
+ * can refer to <tt>this.index</tt>.
+ *
+ * @param {array} array an array, usually of string keys.
+ * @param {function} [f] an optional key function.
+ * @returns {array} the unique values.
+ */
+pv.uniq = function(array, f) {
+  if (!f) f = pv.identity;
+  var map = {}, keys = [], o = {}, y;
+  array.forEach(function(x, i) {
+    o.index = i;
+    y = f.call(o, x);
+    if (!(y in map)) map[y] = keys.push(y);
+  });
+  return keys;
+};
+
+/**
+ * The comparator function for natural order. This can be used in conjunction with
+ * the built-in array <tt>sort</tt> method to sort elements by their natural
+ * order, ascending. Note that if no comparator function is specified to the
+ * built-in <tt>sort</tt> method, the default order is lexicographic, <i>not</i>
+ * natural!
+ *
+ * @see <a
+ * href="http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/sort">Array.sort</a>.
+ * @param a an element to compare.
+ * @param b an element to compare.
+ * @returns {number} negative if a &lt; b; positive if a &gt; b; otherwise 0.
+ */
+pv.naturalOrder = function(a, b) {
+  return (a < b) ? -1 : ((a > b) ? 1 : 0);
+};
+
+/**
+ * The comparator function for reverse natural order. This can be used in
+ * conjunction with the built-in array <tt>sort</tt> method to sort elements by
+ * their natural order, descending. Note that if no comparator function is
+ * specified to the built-in <tt>sort</tt> method, the default order is
+ * lexicographic, <i>not</i> natural!
+ *
+ * @see #naturalOrder
+ * @param a an element to compare.
+ * @param b an element to compare.
+ * @returns {number} negative if a &lt; b; positive if a &gt; b; otherwise 0.
+ */
+pv.reverseOrder = function(b, a) {
+  return (a < b) ? -1 : ((a > b) ? 1 : 0);
+};
+
+/**
+ * Searches the specified array of numbers for the specified value using the
+ * binary search algorithm. The array must be sorted (as by the <tt>sort</tt>
+ * method) prior to making this call. If it is not sorted, the results are
+ * undefined. If the array contains multiple elements with the specified value,
+ * there is no guarantee which one will be found.
+ *
+ * <p>The <i>insertion point</i> is defined as the point at which the value
+ * would be inserted into the array: the index of the first element greater than
+ * the value, or <tt>array.length</tt>, if all elements in the array are less
+ * than the specified value. Note that this guarantees that the return value
+ * will be nonnegative if and only if the value is found.
+ *
+ * @param {number[]} array the array to be searched.
+ * @param {number} value the value to be searched for.
+ * @returns the index of the search value, if it is contained in the array;
+ * otherwise, (-(<i>insertion point</i>) - 1).
+ * @param {function} [f] an optional key function.
+ */
+pv.search = function(array, value, f) {
+  if (!f) f = pv.identity;
+  var low = 0, high = array.length - 1;
+  while (low <= high) {
+    var mid = (low + high) >> 1, midValue = f(array[mid]);
+    if (midValue < value) low = mid + 1;
+    else if (midValue > value) high = mid - 1;
+    else return mid;
+  }
+  return -low - 1;
+};
+
+pv.search.index = function(array, value, f) {
+  var i = pv.search(array, value, f);
+  return (i < 0) ? (-i - 1) : i;
+};

data/vendor/src/data/Dom.js

@@ -0,0 +1,380 @@
+/**
+ * Returns a {@link pv.Dom} operator for the given map. This is a convenience
+ * factory method, equivalent to <tt>new pv.Dom(map)</tt>. To apply the operator
+ * and retrieve the root node, call {@link pv.Dom#root}; to retrieve all nodes
+ * flattened, use {@link pv.Dom#nodes}.
+ *
+ * @see pv.Dom
+ * @param map a map from which to construct a DOM.
+ * @returns {pv.Dom} a DOM operator for the specified map.
+ */
+pv.dom = function(map) {
+  return new pv.Dom(map);
+};
+
+/**
+ * Constructs a DOM operator for the specified map. This constructor should not
+ * be invoked directly; use {@link pv.dom} instead.
+ *
+ * @class Represets a DOM operator for the specified map. This allows easy
+ * transformation of a hierarchical JavaScript object (such as a JSON map) to a
+ * W3C Document Object Model hierarchy. For more information on which attributes
+ * and methods from the specification are supported, see {@link pv.Dom.Node}.
+ *
+ * <p>Leaves in the map are determined using an associated <i>leaf</i> function;
+ * see {@link #leaf}. By default, leaves are any value whose type is not
+ * "object", such as numbers or strings.
+ *
+ * @param map a map from which to construct a DOM.
+ */
+pv.Dom = function(map) {
+  this.$map = map;
+};
+
+/** @private The default leaf function. */
+pv.Dom.prototype.$leaf = function(n) {
+  return typeof n != "object";
+};
+
+/**
+ * Sets or gets the leaf function for this DOM operator. The leaf function
+ * identifies which values in the map are leaves, and which are internal nodes.
+ * By default, objects are considered internal nodes, and primitives (such as
+ * numbers and strings) are considered leaves.
+ *
+ * @param {function} f the new leaf function.
+ * @returns the current leaf function, or <tt>this</tt>.
+ */
+pv.Dom.prototype.leaf = function(f) {
+  if (arguments.length) {
+    this.$leaf = f;
+    return this;
+  }
+  return this.$leaf;
+};
+
+/**
+ * Applies the DOM operator, returning the root node.
+ *
+ * @returns {pv.Dom.Node} the root node.
+ * @param {string} [nodeName] optional node name for the root.
+ */
+pv.Dom.prototype.root = function(nodeName) {
+  var leaf = this.$leaf, root = recurse(this.$map);
+
+  /** @private */
+  function recurse(map) {
+    var n = new pv.Dom.Node();
+    for (var k in map) {
+      var v = map[k];
+      n.appendChild(leaf(v) ? new pv.Dom.Node(v) : recurse(v)).nodeName = k;
+    }
+    return n;
+  }
+
+  root.nodeName = nodeName;
+  return root;
+};
+
+/**
+ * Applies the DOM operator, returning the array of all nodes in preorder
+ * traversal.
+ *
+ * @returns {array} the array of nodes in preorder traversal.
+ */
+pv.Dom.prototype.nodes = function() {
+  return this.root().nodes();
+};
+
+/**
+ * Constructs a DOM node for the specified value. Instances of this class are
+ * not typically created directly; instead they are generated from a JavaScript
+ * map using the {@link pv.Dom} operator.
+ *
+ * @class Represents a <tt>Node</tt> in the W3C Document Object Model.
+ */
+pv.Dom.Node = function(value) {
+  this.nodeValue = value;
+  this.childNodes = [];
+};
+
+/**
+ * The node name. When generated from a map, the node name corresponds to the
+ * key at the given level in the map. Note that the root node has no associated
+ * key, and thus has an undefined node name (and no <tt>parentNode</tt>).
+ *
+ * @type string
+ * @field pv.Dom.Node.prototype.nodeName
+ */
+
+/**
+ * The node value. When generated from a map, node value corresponds to the leaf
+ * value for leaf nodes, and is undefined for internal nodes.
+ *
+ * @field pv.Dom.Node.prototype.nodeValue
+ */
+
+/**
+ * The array of child nodes. This array is empty for leaf nodes. An easy way to
+ * check if child nodes exist is to query <tt>firstChild</tt>.
+ *
+ * @type array
+ * @field pv.Dom.Node.prototype.childNodes
+ */
+
+/**
+ * The parent node, which is null for root nodes.
+ *
+ * @type pv.Dom.Node
+ */
+pv.Dom.Node.prototype.parentNode = null;
+
+/**
+ * The first child, which is null for leaf nodes.
+ *
+ * @type pv.Dom.Node
+ */
+pv.Dom.Node.prototype.firstChild = null;
+
+/**
+ * The last child, which is null for leaf nodes.
+ *
+ * @type pv.Dom.Node
+ */
+pv.Dom.Node.prototype.lastChild = null;
+
+/**
+ * The previous sibling node, which is null for the first child.
+ *
+ * @type pv.Dom.Node
+ */
+pv.Dom.Node.prototype.previousSibling = null;
+
+/**
+ * The next sibling node, which is null for the last child.
+ *
+ * @type pv.Dom.Node
+ */
+pv.Dom.Node.prototype.nextSibling = null;
+
+/**
+ * Removes the specified child node from this node.
+ *
+ * @throws Error if the specified child is not a child of this node.
+ * @returns {pv.Dom.Node} the removed child.
+ */
+pv.Dom.Node.prototype.removeChild = function(n) {
+  var i = this.childNodes.indexOf(n);
+  if (i == -1) throw new Error("child not found");
+  this.childNodes.splice(i, 1);
+  if (n.previousSibling) n.previousSibling.nextSibling = n.nextSibling;
+  else this.firstChild = n.nextSibling;
+  if (n.nextSibling) n.nextSibling.previousSibling = n.previousSibling;
+  else this.lastChild = n.previousSibling;
+  delete n.nextSibling;
+  delete n.previousSibling;
+  delete n.parentNode;
+  return n;
+};
+
+/**
+ * Appends the specified child node to this node. If the specified child is
+ * already part of the DOM, the child is first removed before being added to
+ * this node.
+ *
+ * @returns {pv.Dom.Node} the appended child.
+ */
+pv.Dom.Node.prototype.appendChild = function(n) {
+  if (n.parentNode) n.parentNode.removeChild(n);
+  n.parentNode = this;
+  n.previousSibling = this.lastChild;
+  if (this.lastChild) this.lastChild.nextSibling = n;
+  else this.firstChild = n;
+  this.lastChild = n;
+  this.childNodes.push(n);
+  return n;
+};
+
+/**
+ * Inserts the specified child <i>n</i> before the given reference child
+ * <i>r</i> of this node. If <i>r</i> is null, this method is equivalent to
+ * {@link #appendChild}. If <i>n</i> is already part of the DOM, it is first
+ * removed before being inserted.
+ *
+ * @throws Error if <i>r</i> is non-null and not a child of this node.
+ * @returns {pv.Dom.Node} the inserted child.
+ */
+pv.Dom.Node.prototype.insertBefore = function(n, r) {
+  if (!r) return this.appendChild(n);
+  var i = this.childNodes.indexOf(r);
+  if (i == -1) throw new Error("child not found");
+  if (n.parentNode) n.parentNode.removeChild(n);
+  n.parentNode = this;
+  n.nextSibling = r;
+  n.previousSibling = r.previousSibling;
+  if (r.previousSibling) {
+    r.previousSibling.nextSibling = n;
+  } else {
+    if (r == this.lastChild) this.lastChild = n;
+    this.firstChild = n;
+  }
+  this.childNodes.splice(i, 0, n);
+  return n;
+};
+
+/**
+ * Replaces the specified child <i>r</i> of this node with the node <i>n</i>. If
+ * <i>n</i> is already part of the DOM, it is first removed before being added.
+ *
+ * @throws Error if <i>r</i> is not a child of this node.
+ */
+pv.Dom.Node.prototype.replaceChild = function(n, r) {
+  var i = this.childNodes.indexOf(r);
+  if (i == -1) throw new Error("child not found");
+  if (n.parentNode) n.parentNode.removeChild(n);
+  n.parentNode = this;
+  n.nextSibling = r.nextSibling;
+  n.previousSibling = r.previousSibling;
+  if (r.previousSibling) r.previousSibling.nextSibling = n;
+  else this.firstChild = n;
+  if (r.nextSibling) r.nextSibling.previousSibling = n;
+  else this.lastChild = n;
+  this.childNodes[i] = n;
+  return r;
+};
+
+/**
+ * Visits each node in the tree in preorder traversal, applying the specified
+ * function <i>f</i>. The arguments to the function are:<ol>
+ *
+ * <li>The current node.
+ * <li>The current depth, starting at 0 for the root node.</ol>
+ *
+ * @param {function} f a function to apply to each node.
+ */
+pv.Dom.Node.prototype.visitBefore = function(f) {
+  function visit(n, i) {
+    f(n, i);
+    for (var c = n.firstChild; c; c = c.nextSibling) {
+      visit(c, i + 1);
+    }
+  }
+  visit(this, 0);
+};
+
+/**
+ * Visits each node in the tree in postorder traversal, applying the specified
+ * function <i>f</i>. The arguments to the function are:<ol>
+ *
+ * <li>The current node.
+ * <li>The current depth, starting at 0 for the root node.</ol>
+ *
+ * @param {function} f a function to apply to each node.
+ */
+pv.Dom.Node.prototype.visitAfter = function(f) {
+  function visit(n, i) {
+    for (var c = n.firstChild; c; c = c.nextSibling) {
+      visit(c, i + 1);
+    }
+    f(n, i);
+  }
+  visit(this, 0);
+};
+
+/**
+ * Sorts child nodes of this node, and all descendent nodes recursively, using
+ * the specified comparator function <tt>f</tt>. The comparator function is
+ * passed two nodes to compare.
+ *
+ * <p>Note: during the sort operation, the comparator function should not rely
+ * on the tree being well-formed; the values of <tt>previousSibling</tt> and
+ * <tt>nextSibling</tt> for the nodes being compared are not defined during the
+ * sort operation.
+ *
+ * @param {function} f a comparator function.
+ * @returns this.
+ */
+pv.Dom.Node.prototype.sort = function(f) {
+  if (this.firstChild) {
+    this.childNodes.sort(f);
+    var p = this.firstChild = this.childNodes[0], c;
+    delete p.previousSibling;
+    for (var i = 1; i < this.childNodes.length; i++) {
+      p.sort(f);
+      c = this.childNodes[i];
+      c.previousSibling = p;
+      p = p.nextSibling = c;
+    }
+    this.lastChild = p;
+    delete p.nextSibling;
+    p.sort(f);
+  }
+  return this;
+};
+
+/**
+ * Reverses all sibling nodes.
+ *
+ * @returns this.
+ */
+pv.Dom.Node.prototype.reverse = function() {
+  var childNodes = [];
+  this.visitAfter(function(n) {
+      while (n.lastChild) childNodes.push(n.removeChild(n.lastChild));
+      for (var c; c = childNodes.pop();) n.insertBefore(c, n.firstChild);
+    });
+  return this;
+};
+
+/** Returns all descendants of this node in preorder traversal. */
+pv.Dom.Node.prototype.nodes = function() {
+  var array = [];
+
+  /** @private */
+  function flatten(node) {
+    array.push(node);
+    node.childNodes.forEach(flatten);
+  }
+
+  flatten(this, array);
+  return array;
+};
+
+/**
+ * Toggles the child nodes of this node. If this node is not yet toggled, this
+ * method removes all child nodes and appends them to a new <tt>toggled</tt>
+ * array attribute on this node. Otherwise, if this node is toggled, this method
+ * re-adds all toggled child nodes and deletes the <tt>toggled</tt> attribute.
+ *
+ * <p>This method has no effect if the node has no child nodes.
+ *
+ * @param {boolean} [recursive] whether the toggle should apply to descendants.
+ */
+pv.Dom.Node.prototype.toggle = function(recursive) {
+  if (recursive) return this.toggled
+      ? this.visitBefore(function(n) { if (n.toggled) n.toggle(); })
+      : this.visitAfter(function(n) { if (!n.toggled) n.toggle(); });
+  var n = this;
+  if (n.toggled) {
+    for (var c; c = n.toggled.pop();) n.appendChild(c);
+    delete n.toggled;
+  } else if (n.lastChild) {
+    n.toggled = [];
+    while (n.lastChild) n.toggled.push(n.removeChild(n.lastChild));
+  }
+};
+
+/**
+ * Given a flat array of values, returns a simple DOM with each value wrapped by
+ * a node that is a child of the root node.
+ *
+ * @param {array} values.
+ * @returns {array} nodes.
+ */
+pv.nodes = function(values) {
+  var root = new pv.Dom.Node();
+  for (var i = 0; i < values.length; i++) {
+    root.appendChild(new pv.Dom.Node(values[i]));
+  }
+  return root.nodes();
+};