rubyvis 0.1.0 → 0.1.1

data/vendor/src/mark/Panel.js

@@ -0,0 +1,273 @@
+/**
+ * Constructs a new, empty panel with default properties. Panels, with the
+ * exception of the root panel, are not typically constructed directly; instead,
+ * they are added to an existing panel or mark via {@link pv.Mark#add}.
+ *
+ * @class Represents a container mark. Panels allow repeated or nested
+ * structures, commonly used in small multiple displays where a small
+ * visualization is tiled to facilitate comparison across one or more
+ * dimensions. Other types of visualizations may benefit from repeated and
+ * possibly overlapping structure as well, such as stacked area charts. Panels
+ * can also offset the position of marks to provide padding from surrounding
+ * content.
+ *
+ * <p>All Protovis displays have at least one panel; this is the root panel to
+ * which marks are rendered. The box model properties (four margins, width and
+ * height) are used to offset the positions of contained marks. The data
+ * property determines the panel count: a panel is generated once per associated
+ * datum. When nested panels are used, property functions can declare additional
+ * arguments to access the data associated with enclosing panels.
+ *
+ * <p>Panels can be rendered inline, facilitating the creation of sparklines.
+ * This allows designers to reuse browser layout features, such as text flow and
+ * tables; designers can also overlay HTML elements such as rich text and
+ * images.
+ *
+ * <p>All panels have a <tt>children</tt> array (possibly empty) containing the
+ * child marks in the order they were added. Panels also have a <tt>root</tt>
+ * field which points to the root (outermost) panel; the root panel's root field
+ * points to itself.
+ *
+ * <p>See also the <a href="../../api/">Protovis guide</a>.
+ *
+ * @extends pv.Bar
+ */
+pv.Panel = function() {
+  pv.Bar.call(this);
+
+  /**
+   * The child marks; zero or more {@link pv.Mark}s in the order they were
+   * added.
+   *
+   * @see #add
+   * @type pv.Mark[]
+   */
+  this.children = [];
+  this.root = this;
+
+  /**
+   * The internal $dom field is set by the Protovis loader; see lang/init.js. It
+   * refers to the script element that contains the Protovis specification, so
+   * that the panel knows where in the DOM to insert the generated SVG element.
+   *
+   * @private
+   */
+  this.$dom = pv.$ && pv.$.s;
+};
+
+pv.Panel.prototype = pv.extend(pv.Bar)
+    .property("transform")
+    .property("overflow", String)
+    .property("canvas", function(c) {
+        return (typeof c == "string")
+            ? document.getElementById(c)
+            : c; // assume that c is the passed-in element
+      });
+
+pv.Panel.prototype.type = "panel";
+
+/**
+ * The canvas element; either the string ID of the canvas element in the current
+ * document, or a reference to the canvas element itself. If null, a canvas
+ * element will be created and inserted into the document at the location of the
+ * script element containing the current Protovis specification. This property
+ * only applies to root panels and is ignored on nested panels.
+ *
+ * <p>Note: the "canvas" element here refers to a <tt>div</tt> (or other suitable
+ * HTML container element), <i>not</i> a <tt>canvas</tt> element. The name of
+ * this property is a historical anachronism from the first implementation that
+ * used HTML 5 canvas, rather than SVG.
+ *
+ * @type string
+ * @name pv.Panel.prototype.canvas
+ */
+
+/**
+ * Specifies whether child marks are clipped when they overflow this panel.
+ * This affects the clipping of all this panel's descendant marks.
+ *
+ * @type string
+ * @name pv.Panel.prototype.overflow
+ * @see <a href="http://www.w3.org/TR/CSS2/visufx.html#overflow">CSS2</a>
+ */
+
+/**
+ * The transform to be applied to child marks. The default transform is
+ * identity, which has no effect. Note that the panel's own fill and stroke are
+ * not affected by the transform, and panel's transform only affects the
+ * <tt>scale</tt> of child marks, not the panel itself.
+ *
+ * @type pv.Transform
+ * @name pv.Panel.prototype.transform
+ * @see pv.Mark#scale
+ */
+
+/**
+ * Default properties for panels. By default, the margins are zero, the fill
+ * style is transparent.
+ *
+ * @type pv.Panel
+ */
+pv.Panel.prototype.defaults = new pv.Panel()
+    .extend(pv.Bar.prototype.defaults)
+    .fillStyle(null) // override Bar default
+    .overflow("visible");
+
+/**
+ * Returns an anchor with the specified name. This method is overridden such
+ * that adding to a panel's anchor adds to the panel, rather than to the panel's
+ * parent.
+ *
+ * @param {string} name the anchor name; either a string or a property function.
+ * @returns {pv.Anchor} the new anchor.
+ */
+pv.Panel.prototype.anchor = function(name) {
+  var anchor = pv.Bar.prototype.anchor.call(this, name);
+  anchor.parent = this;
+  return anchor;
+};
+
+/**
+ * Adds a new mark of the specified type to this panel. Unlike the normal
+ * {@link Mark#add} behavior, adding a mark to a panel does not cause the mark
+ * to inherit from the panel. Since the contained marks are offset by the panel
+ * margins already, inheriting properties is generally undesirable; of course,
+ * it is always possible to change this behavior by calling {@link Mark#extend}
+ * explicitly.
+ *
+ * @param {function} type the type of the new mark to add.
+ * @returns {pv.Mark} the new mark.
+ */
+pv.Panel.prototype.add = function(type) {
+  var child = new type();
+  child.parent = this;
+  child.root = this.root;
+  child.childIndex = this.children.length;
+  this.children.push(child);
+  return child;
+};
+
+/** @private Bind this panel, then any child marks recursively. */
+pv.Panel.prototype.bind = function() {
+  pv.Mark.prototype.bind.call(this);
+  for (var i = 0; i < this.children.length; i++) {
+    this.children[i].bind();
+  }
+};
+
+/**
+ * @private Evaluates all of the properties for this panel for the specified
+ * instance <tt>s</tt> in the scene graph, including recursively building the
+ * scene graph for child marks.
+ *
+ * @param s a node in the scene graph; the instance of the panel to build.
+ * @see Mark#scene
+ */
+pv.Panel.prototype.buildInstance = function(s) {
+  pv.Bar.prototype.buildInstance.call(this, s);
+  if (!s.visible) return;
+  if (!s.children) s.children = [];
+
+  /*
+   * Multiply the current scale factor by this panel's transform. Also clear the
+   * default index as we recurse into child marks; it will be reset to the
+   * current index when the next panel instance is built.
+   */
+  var scale = this.scale * s.transform.k, child, n = this.children.length;
+  pv.Mark.prototype.index = -1;
+
+  /*
+   * Build each child, passing in the parent (this panel) scene graph node. The
+   * child mark's scene is initialized from the corresponding entry in the
+   * existing scene graph, such that properties from the previous build can be
+   * reused; this is largely to facilitate the recycling of SVG elements.
+   */
+  for (var i = 0; i < n; i++) {
+    child = this.children[i];
+    child.scene = s.children[i]; // possibly undefined
+    child.scale = scale;
+    child.build();
+  }
+
+  /*
+   * Once the child marks have been built, the new scene graph nodes are removed
+   * from the child marks and placed into the scene graph. The nodes cannot
+   * remain on the child nodes because this panel (or a parent panel) may be
+   * instantiated multiple times!
+   */
+  for (var i = 0; i < n; i++) {
+    child = this.children[i];
+    s.children[i] = child.scene;
+    delete child.scene;
+    delete child.scale;
+  }
+
+  /* Delete any expired child scenes. */
+  s.children.length = n;
+};
+
+/**
+ * @private Computes the implied properties for this panel for the specified
+ * instance <tt>s</tt> in the scene graph. Panels have two implied
+ * properties:<ul>
+ *
+ * <li>The <tt>canvas</tt> property references the DOM element, typically a DIV,
+ * that contains the SVG element that is used to display the visualization. This
+ * property may be specified as a string, referring to the unique ID of the
+ * element in the DOM. The string is converted to a reference to the DOM
+ * element. The width and height of the SVG element is inferred from this DOM
+ * element. If no canvas property is specified, a new SVG element is created and
+ * inserted into the document, using the panel dimensions; see
+ * {@link #createCanvas}.
+ *
+ * <li>The <tt>children</tt> array, while not a property per se, contains the
+ * scene graph for each child mark. This array is initialized to be empty, and
+ * is populated above in {@link #buildInstance}.
+ *
+ * </ul>The current implementation creates the SVG element, if necessary, during
+ * the build phase; in the future, it may be preferrable to move this to the
+ * update phase, although then the canvas property would be undefined. In
+ * addition, DOM inspection is necessary to define the implied width and height
+ * properties that may be inferred from the DOM.
+ *
+ * @param s a node in the scene graph; the instance of the panel to build.
+ */
+pv.Panel.prototype.buildImplied = function(s) {
+  if (!this.parent) {
+    var c = s.canvas;
+    if (c) {
+      /* Clear the container if it's not associated with this panel. */
+      if (c.$panel != this) {
+        c.$panel = this;
+        while (c.lastChild) c.removeChild(c.lastChild);
+      }
+
+      /* If width and height weren't specified, inspect the container. */
+      var w, h;
+      if (s.width == null) {
+        w = parseFloat(pv.css(c, "width"));
+        s.width = w - s.left - s.right;
+      }
+      if (s.height == null) {
+        h = parseFloat(pv.css(c, "height"));
+        s.height = h - s.top - s.bottom;
+      }
+    } else {
+      var cache = this.$canvas || (this.$canvas = []);
+      if (!(c = cache[this.index])) {
+        c = cache[this.index] = document.createElement("span");
+        if (this.$dom) { // script element for text/javascript+protovis
+          this.$dom.parentNode.insertBefore(c, this.$dom);
+        } else { // find the last element in the body
+          var n = document.body;
+          while (n.lastChild && n.lastChild.tagName) n = n.lastChild;
+          if (n != document.body) n = n.parentNode;
+          n.appendChild(c);
+        }
+      }
+    }
+    s.canvas = c;
+  }
+  if (!s.transform) s.transform = pv.Transform.identity;
+  pv.Mark.prototype.buildImplied.call(this, s);
+};

data/vendor/src/mark/Rule.js

@@ -0,0 +1,143 @@
+/**
+ * Constructs a new rule with default properties. Rules are not typically
+ * constructed directly, but by adding to a panel or an existing mark via
+ * {@link pv.Mark#add}.
+ *
+ * @class Represents a horizontal or vertical rule. Rules are frequently used
+ * for axes and grid lines. For example, specifying only the bottom property
+ * draws horizontal rules, while specifying only the left draws vertical
+ * rules. Rules can also be used as thin bars. The visual style is controlled in
+ * the same manner as lines.
+ *
+ * <p>Rules are positioned exclusively the standard box model properties. The
+ * following combinations of properties are supported:
+ *
+ * <table>
+ * <thead><th style="width:12em;">Properties</th><th>Orientation</th></thead>
+ * <tbody>
+ * <tr><td>left</td><td>vertical</td></tr>
+ * <tr><td>right</td><td>vertical</td></tr>
+ * <tr><td>left, bottom, top</td><td>vertical</td></tr>
+ * <tr><td>right, bottom, top</td><td>vertical</td></tr>
+ * <tr><td>top</td><td>horizontal</td></tr>
+ * <tr><td>bottom</td><td>horizontal</td></tr>
+ * <tr><td>top, left, right</td><td>horizontal</td></tr>
+ * <tr><td>bottom, left, right</td><td>horizontal</td></tr>
+ * <tr><td>left, top, height</td><td>vertical</td></tr>
+ * <tr><td>left, bottom, height</td><td>vertical</td></tr>
+ * <tr><td>right, top, height</td><td>vertical</td></tr>
+ * <tr><td>right, bottom, height</td><td>vertical</td></tr>
+ * <tr><td>left, top, width</td><td>horizontal</td></tr>
+ * <tr><td>left, bottom, width</td><td>horizontal</td></tr>
+ * <tr><td>right, top, width</td><td>horizontal</td></tr>
+ * <tr><td>right, bottom, width</td><td>horizontal</td></tr>
+ * </tbody>
+ * </table>
+ *
+ * <p>Small rules can be used as tick marks; alternatively, a {@link Dot} with
+ * the "tick" shape can be used.
+ *
+ * <p>See also the <a href="../../api/Rule.html">Rule guide</a>.
+ *
+ * @see pv.Line
+ * @extends pv.Mark
+ */
+pv.Rule = function() {
+  pv.Mark.call(this);
+};
+
+pv.Rule.prototype = pv.extend(pv.Mark)
+    .property("width", Number)
+    .property("height", Number)
+    .property("lineWidth", Number)
+    .property("strokeStyle", pv.color);
+
+pv.Rule.prototype.type = "rule";
+
+/**
+ * The width of the rule, in pixels. If the left position is specified, the rule
+ * extends rightward from the left edge; if the right position is specified, the
+ * rule extends leftward from the right edge.
+ *
+ * @type number
+ * @name pv.Rule.prototype.width
+ */
+
+/**
+ * The height of the rule, in pixels. If the bottom position is specified, the
+ * rule extends upward from the bottom edge; if the top position is specified,
+ * the rule extends downward from the top edge.
+ *
+ * @type number
+ * @name pv.Rule.prototype.height
+ */
+
+/**
+ * The width of stroked lines, in pixels; used in conjunction with
+ * <tt>strokeStyle</tt> to stroke the rule. The default value is 1 pixel.
+ *
+ * @type number
+ * @name pv.Rule.prototype.lineWidth
+ */
+
+/**
+ * The style of stroked lines; used in conjunction with <tt>lineWidth</tt> to
+ * stroke the rule. The default value of this property is black.
+ *
+ * @type string
+ * @name pv.Rule.prototype.strokeStyle
+ * @see pv.color
+ */
+
+/**
+ * Default properties for rules. By default, a single-pixel black line is
+ * stroked.
+ *
+ * @type pv.Rule
+ */
+pv.Rule.prototype.defaults = new pv.Rule()
+    .extend(pv.Mark.prototype.defaults)
+    .lineWidth(1)
+    .strokeStyle("black")
+    .antialias(false);
+
+/**
+ * Constructs a new rule anchor with default properties. Rules support five
+ * different anchors:<ul>
+ *
+ * <li>top
+ * <li>left
+ * <li>center
+ * <li>bottom
+ * <li>right
+ *
+ * </ul>In addition to positioning properties (left, right, top bottom), the
+ * anchors support text rendering properties (text-align, text-baseline). Text is
+ * rendered to appear outside the rule. Note that this behavior is different
+ * from other mark anchors, which default to rendering text <i>inside</i> the
+ * mark.
+ *
+ * <p>For consistency with the other mark types, the anchor positions are
+ * defined in terms of their opposite edge. For example, the top anchor defines
+ * the bottom property, such that a bar added to the top anchor grows upward.
+ *
+ * @param {string} name the anchor name; either a string or a property function.
+ * @returns {pv.Anchor}
+ */
+pv.Rule.prototype.anchor = pv.Line.prototype.anchor;
+
+/** @private Sets width or height based on orientation. */
+pv.Rule.prototype.buildImplied = function(s) {
+  var l = s.left, r = s.right, t = s.top, b = s.bottom;
+
+  /* Determine horizontal or vertical orientation. */
+  if ((s.width != null)
+      || ((l == null) && (r == null))
+      || ((r != null) && (l != null))) {
+    s.height = 0;
+  } else {
+    s.width = 0;
+  }
+
+  pv.Mark.prototype.buildImplied.call(this, s);
+};

data/vendor/src/mark/Transient.js

@@ -0,0 +1,7 @@
+pv.Transient = function(mark) {
+  pv.Mark.call(this);
+  this.fillStyle(null).strokeStyle(null).textStyle(null);
+  this.on = function(state) { return mark.on(state); };
+};
+
+pv.Transient.prototype = pv.extend(pv.Mark);

data/vendor/src/mark/Transition.js

@@ -0,0 +1,195 @@
+pv.Transition = function(mark) {
+  var that = this,
+      ease = pv.ease("cubic-in-out"),
+      duration = 250,
+      timer;
+
+  var interpolated = {
+    top: 1,
+    left: 1,
+    right: 1,
+    bottom: 1,
+    width: 1,
+    height: 1,
+    innerRadius: 1,
+    outerRadius: 1,
+    radius: 1,
+    startAngle: 1,
+    endAngle: 1,
+    angle: 1,
+    fillStyle: 1,
+    strokeStyle: 1,
+    lineWidth: 1,
+    eccentricity: 1,
+    tension: 1,
+    textAngle: 1,
+    textStyle: 1,
+    textMargin: 1
+  };
+
+  var defaults = new pv.Transient();
+
+  var none = pv.Color.transparent;
+
+  /** @private */
+  function ids(marks) {
+    var map = {};
+    for (var i = 0; i < marks.length; i++) {
+      var mark = marks[i];
+      if (mark.id) map[mark.id] = mark;
+    }
+    return map;
+  }
+
+  /** @private */
+  function interpolateProperty(list, name, before, after) {
+    if (name in interpolated) {
+      var i = pv.Scale.interpolator(before[name], after[name]);
+      var f = function(t) { before[name] = i(t); }
+    } else {
+      var f = function(t) { if (t > .5) before[name] = after[name]; }
+    }
+    f.next = list.head;
+    list.head = f;
+  }
+
+  /** @private */
+  function interpolateInstance(list, before, after) {
+    for (var name in before) {
+      if (name == "children") continue; // not a property
+      if (before[name] == after[name]) continue; // unchanged
+      interpolateProperty(list, name, before, after);
+    }
+    if (before.children) {
+      for (var j = 0; j < before.children.length; j++) {
+        interpolate(list, before.children[j], after.children[j]);
+      }
+    }
+  }
+
+  /** @private */
+  function interpolate(list, before, after) {
+    var mark = before.mark, bi = ids(before), ai = ids(after);
+    for (var i = 0; i < before.length; i++) {
+      var b = before[i], a = b.id ? ai[b.id] : after[i];
+      b.index = i;
+      if (!b.visible) continue;
+      if (!(a && a.visible)) {
+        var o = override(before, i, mark.$exit, after);
+
+        /*
+         * After the transition finishes, we need to do a little cleanup to
+         * insure that the final state of the scenegraph is consistent with the
+         * "after" render. For instances that were removed, we need to remove
+         * them from the scenegraph; for instances that became invisible, we
+         * need to mark them invisible. See the cleanup method for details.
+         */
+        b.transition = a ? 2 : (after.push(o), 1);
+        a = o;
+      }
+      interpolateInstance(list, b, a);
+    }
+    for (var i = 0; i < after.length; i++) {
+      var a = after[i], b = a.id ? bi[a.id] : before[i];
+      if (!(b && b.visible) && a.visible) {
+        var o = override(after, i, mark.$enter, before);
+        if (!b) before.push(o);
+        else before[b.index] = o;
+        interpolateInstance(list, o, a);
+      }
+    }
+  }
+
+  /** @private */
+  function override(scene, index, proto, other) {
+    var s = pv.extend(scene[index]),
+        m = scene.mark,
+        r = m.root.scene,
+        p = (proto || defaults).$properties,
+        t;
+
+    /* Correct the target reference, if this is an anchor. */
+    if (other.target && (t = other.target[other.length])) {
+      scene = pv.extend(scene);
+      scene.target = pv.extend(other.target);
+      scene.target[index] = t;
+    }
+
+    /* Determine the set of properties to evaluate. */
+    var seen = {};
+    for (var i = 0; i < p.length; i++) seen[p[i].name] = 1;
+    p = m.binds.optional
+        .filter(function(p) { return !(p.name in seen); })
+        .concat(p);
+
+    /* Evaluate the properties and update any implied ones. */
+    m.context(scene, index, function() {
+      this.buildProperties(s, p);
+      this.buildImplied(s);
+    });
+
+    /* Restore the root scene. This should probably be done by context(). */
+    m.root.scene = r;
+    return s;
+  }
+
+  /** @private */
+  function cleanup(scene) {
+    for (var i = 0, j = 0; i < scene.length; i++) {
+      var s = scene[i];
+      if (s.transition != 1) {
+        scene[j++] = s;
+        if (s.transition == 2) s.visible = false;
+        if (s.children) s.children.forEach(cleanup);
+      }
+    }
+    scene.length = j;
+  }
+
+  that.ease = function(x) {
+    return arguments.length
+        ? (ease = typeof x == "function" ? x : pv.ease(x), that)
+        : ease;
+  };
+
+  that.duration = function(x) {
+    return arguments.length
+        ? (duration = Number(x), that)
+        : duration;
+  };
+
+  that.start = function() {
+    // TODO allow partial rendering
+    if (mark.parent) fail();
+
+    // TODO allow parallel and sequenced transitions
+    if (mark.$transition) mark.$transition.stop();
+    mark.$transition = that;
+
+    // TODO clearing the scene like this forces total re-build
+    var i = pv.Mark.prototype.index, before = mark.scene, after;
+    mark.scene = null;
+    mark.bind();
+    mark.build();
+    after = mark.scene;
+    mark.scene = before;
+    pv.Mark.prototype.index = i;
+
+    var start = Date.now(), list = {};
+    interpolate(list, before, after);
+    timer = setInterval(function() {
+      var t = Math.max(0, Math.min(1, (Date.now() - start) / duration)),
+          e = ease(t);
+      for (var i = list.head; i; i = i.next) i(e);
+      if (t == 1) {
+        cleanup(mark.scene);
+        that.stop();
+      }
+      pv.Scene.updateAll(before);
+    }, 24);
+  };
+
+  that.stop = function() {
+    clearInterval(timer);
+  };
+};