yui/yui3 — pull request #429 by rgrove (2013-02-01 00:50:48+00:00)
Title: Y.Tree: An awesome generic tree data structure

# Y.Tree

This is an import of the [SmugMug Tree](https://github.com/smugmug/yui-gallery/tree/master/src/sm-tree) gallery module, a generic tree data structure that provides a fast and friendly API for working with hierarchical data (such as the items in a Menu, TreeView, or even a DOM node).

## What it does

A tree has a root node, which may contain any number of child nodes, which may themselves contain child nodes, ad infinitum.

Child nodes (`Y.Tree.Node`) are lightweight function instances which delegate to the tree for all significant functionality, so trees remain performant and memory-efficient even with thousands and thousands of nodes.

Don't believe me? Here's a stress test that demonstrates the SmugMug TreeView gallery module (which uses `Y.Tree`) loading and rendering 12,780 nodes in about 100ms:

The `Y.Tree` class doesn't expose any UI, but the following gallery modules are examples of components that extend `Y.Tree` and provide a UI:

* [SmugMug Menu](https://github.com/smugmug/yui-gallery/tree/master/src/sm-menu)
* [SmugMug TreeView](https://github.com/smugmug/yui-gallery/tree/master/src/sm-treeview)

## Why YUI needs it

Tree structures are inherently useful for representing many types of data that web developers work with frequently. YUI currently has components such as Model and ModelList that are good for working with flat lists, but these components are awkward to use and perform poorly when shoehorned into representing hierarchical data.

Some of the most obvious potential use cases for a tree structure would be a treeview widget or a hierarchical menu. Here are a few other possible use cases to spur your imagination:

* A future version of `Y.NodeList` could adopt `Y.Tree` to represent a hierarchy of DOM nodes.
* `Y.App` could adopt `Y.Tree` to represent a hierarchy of views.
* A parser might use `Y.Tree` to represent a parse tree.

## Act now and get these extensions for free!

This pull request includes several `Y.Tree` extensions that can be used to mix additional functionality into a tree:

* **`Y.Tree.Openable`**: Adds the concept of openable/closeable/toggleable nodes to a Tree, along with related events and methods.

* **`Y.Tree.Selectable`**: Adds the concept of selection state to a Tree, along with related events and methods. In single-select mode (the default) one node at a time may be designated as selected. In the optional multi-select node, multiple nodes may be designated as selected.

Also included is a plugin, `Y.Plugin.Tree.Lazy`, which can be plugged into any Tree that mixes in the `Y.Tree.Openable` extension. This plugin adds a convenient API for lazy-loading children of a node the first time that node is opened.

## Other stuff

`Y.Tree` and friends have full test coverage and detailed API docs. There currently is not a user guide or examples, but I hereby promise to write those if there's a consensus that this PR should be accepted.